Shoelace / Astro best practices #2056

b-d-m-p · 2024-06-09T09:01:47Z

b-d-m-p
Jun 9, 2024

I would appreciate any guidance on best practices for using Shoelace in Astro. I have a working Astro / Shoelace set up, that solves a particular issue I have, but using Shoelace is not very straight forward and examples I've seen vary wildly. I'd like to make a starter project for Shoelace for others, so they have a clear approach to using Shoelace in Astro.

I've included specific questions at the bottom, but you might want to read the steps I went through to see what I ended up with.

I apologize if this is a bit chaotic, it just shows how little information there is on using Shoelace in Astro.

Here's a bit of background. Astro has some documentation on using Lit, but it assumes that you are making your own web components, not using a web component library.

Also, my set up is unique because I have a background-color/scheme transition that fades between light and dark along with view transitions, and for whatever reason, the set up that I thought would be optimal for Shoelace in Astro prevents this from working. I will explain below.

So here a few setups I went through. I originally had my set up working one way, from examples I found on the web, but I couldn't set the default animations for the tool tip, so I made a Shoelace discussion. In the solution example, the code looks like this:

// Ex. A
// src/layouts/BaseLayout.astro

---
import { ViewTransitions } from "astro:transitions"
import { fade } from "astro:transitions"
---

<html>
  <body>
    <sl-switch is:inline>Switch</sl-switch>
    <sl-dropdown>
      <sl-button slot="trigger" caret class="rounded-full"
        class="[&::part(base)]:rounded-xl min-h-[44px]"
      >Edit</sl-button>
      <sl-menu>
        <sl-menu-item value="cut">Cut</sl-menu-item>
        <sl-menu-item value="copy">Copy</sl-menu-item>
        <sl-menu-item value="paste">Paste</sl-menu-item>
      </sl-menu>
    </sl-dropdown>
  </body>
<html>

<script>
import "@shoelace-style/shoelace"

import { setDefaultAnimation } from "@shoelace-style/shoelace/dist/utilities/animation-registry.js"

 setDefaultAnimation("tooltip.show", {
  ...
  })
</script>

The code above works, but later I realized that my transitions were not working, and I thought it was due to the light/dark theme color-scheme: property, but after testing if I completely disable the css, it still happens, so I knew it was something else.

Later I realized that if the import "@shoelace-style/shoelace" is there the transition issue appears, but it is not related to css—it is related to js in some way. And in trying to fix that I ended up trying other people's set ups like the one below, which is only js, and that also caused the issue.

<script type="module" src="/node_modules/@shoelace-style/shoelace/dist/shoelace.js"></script>

After testing several ways of doing it, and stumbled across the fact that individual js imports solve the issue.

So, now I have something like the below...

// Ex. B
// src/layouts/BaseLayout.astro

---
import { ViewTransitions } from "astro:transitions"
import { fade } from "astro:transitions"
---

<html>
  <head>
     <script>
      import "@shoelace-style/shoelace/dist/components/button/button.js"
      import "@shoelace-style/shoelace/dist/components/dropdown/dropdown.js"
      import "@shoelace-style/shoelace/dist/components/switch/switch.js"
      import "@shoelace-style/shoelace/dist/components/menu-item/menu-item.js"
      import "@shoelace-style/shoelace/dist/components/menu-label/menu-label.js"
    </script>
  </head>

  <body>
    <sl-switch is:inline>Switch</sl-switch>
    <sl-dropdown>
      <sl-button slot="trigger" caret class="rounded-full"
        class="[&::part(base)]:rounded-xl min-h-[44px]"
      >Edit</sl-button>
      <sl-menu>
        <sl-menu-item value="cut">Cut</sl-menu-item>
        <sl-menu-item value="copy">Copy</sl-menu-item>
        <sl-menu-item value="paste">Paste</sl-menu-item>
      </sl-menu>
    </sl-dropdown>
  </body>
<html>

<script is:inline>

import { setDefaultAnimation } from "@shoelace-style/shoelace/dist/utilities/animation-registry.js"

 setDefaultAnimation("tooltip.show", {
  ...
  })
</script>

This works, but I am concerned it is not a best practice, and I am confused as to how web components work in Astro in some ways.

One other thing to keep in mind is that in order for some js to work properly with Astro's view transitions some js needs this is:inline on the script tag. Incidentally, in Ex. A, if the script tag is on it, the js for the components doesn't load at all. (You do need it when setting the default animations though.)

So my questions are...

(All of these questions assume importing of Shoelace through npm, not a cdn.)

1. Why do you not have to import Shoelace components, like you would in React?

2. Why do Shoelace components not need `client:load` like framework components?

Strangely, Shoelace components work with out it and if you do use this on a Shoelace component, it complains of an import error.

3. Should shoelace be imported in one import or individually?

4. Where should Shoelace components be imported in Astro?

There are several ways to import that I've seen, some work with certain types of imports and some with others. And there are several places to import:

in the --- section in the top of an astro file
in a script tag in the html head
in a script tag at the bottom of the body
in a script tag that is outside of the html (like Svelte)

5. Bonus: what javascript would cause the background transitions to stop working?

This is specific to my set up, but after narrowing it down to js, I am very curious.

Anyway, sorry for all the questions. I will make somethign for others, so people don't have to struggle with these questions in the future. Cheers.

b-d-m-p · 2024-06-11T09:21:48Z

b-d-m-p
Jun 11, 2024
Author

5. Bonus: what javascript would cause the background transitions to stop working?

Found the cause of no. 5, the background transition issue. Something in the tooltip js is doing it.
import "@shoelace-style/shoelace/dist/components/tooltip/tooltip.js"
Working on figuring out exactly what it is.

1 reply

b-d-m-p Jun 11, 2024
Author

Actually, I should specify that the transitions actually still work, but in dark mode there is a flash of the white theme (Astro docs warn about a similar issue, but this differs from that).

b-d-m-p · 2024-06-11T09:28:13Z

b-d-m-p
Jun 11, 2024
Author

3. Should shoelace be imported in one import or individually?

Based on the cherrypicking section in the the installation page of the docs, it seems either approach is fine.

https://shoelace.style/getting-started/installation#cherry-picking

2 replies

b-d-m-p Jun 11, 2024
Author

Still where to import for each approach is still unclear to me.

b-d-m-p Jul 2, 2024
Author

Also as I say in this comment #2056 (reply in thread), I wonder why Lit components & Shoelace components get imported in different ways.

b2m9 · 2024-07-01T18:53:28Z

b2m9
Jul 1, 2024

@b-d-m-p I can't really help you with your actual problem but I can answer this question for you:

Why do you not have to import Shoelace components, like you would in React?

You actually do, that's what you do here:

<script>
  import "@shoelace-style/shoelace/dist/components/button/button.js"
  import "@shoelace-style/shoelace/dist/components/dropdown/dropdown.js"
  import "@shoelace-style/shoelace/dist/components/switch/switch.js"
  import "@shoelace-style/shoelace/dist/components/menu-item/menu-item.js"
  import "@shoelace-style/shoelace/dist/components/menu-label/menu-label.js"
</script>

Those files register the Custom Element in the page so the browser knows what to render when you use sl-button. You're right that you don't import them in the same way as a React component. But you still have to import them somehow to let the browser know what sl-button means - that's what you do when you add the respective file to the script block above.

3 replies

b-d-m-p Jul 2, 2024
Author

@b2m9 thanks for your reply. I think my question is unclear maybe. It would better be phrased as "Why do you not have to import Shoelace components individually in each file you use them in, like you would in react"

It's great that you don't have to import in every file, but from the perspective of a dev who mainly works with React, Svelte, Vue, etc., it is confusing/surprising. And not that it is the job of the docs, but they don't specify this difference. It's a selling point I think, so making that clear would attract people maybe.

I guess I understand that it just works from having the one main import, but I am still curious as to why, like why does react need them in all the files and Shoelace doesn't? I guess it would be related to how the code compiles and is rendered in the dom—web components are just custom html/js, so if the import is in the root, they get recognized in the dom, but React is passing JavaScript that needs to know what it is looking for to create the virtual dom? Maybe? I have no idea what I am talking about. 😆

I guess that is related to this question ...

Why do Shoelace components not need client:load like framework components?

It doesn't need to make an Island because it's not using JavaScript to render the component, maybe?

What is weird though is that Lit components do need this according to the astro docs. This is their example:

---
import { MyElement } from '../components/my-element.js';
---

<MyElement client:visible />

But they are also importing the components like you would with react. So, consuming a Lit components like Shoelace require different types of imports than rendering a local component built with Lit? So strange. Do you see why I am confused? 😆

b2m9 Jul 2, 2024

Why do Shoelace components not need client:load like framework components?

They do if you get SSR to work. Those client directives are for server-rendered components and specify how they should be hydrated on the client.

Right now, I (and you too) only get the Shoelace components to work on the client - without any actual render on the server. You can see that when you throttle your network speed in the dev tools or deactivate JS. Then sl-button is rendered like a unknown HTML tag (like a div) until the JS portion is loaded on the client, then it renders the sl-button element accordingly. This is exactly why you have to import those components in a script block - so that they're available on the client (that's basically a global import).

What my (and probably your) goal is: SSR support. Render the Shoelace button on the server, then hydrate it when necessary (e.g. with client:idle). In that case you would have to use Astro's Lit integration and import it like this:

---
import SlButton from "@shoelace-style/shoelace/dist/components/button/button.js";
---

<SlButton client:idle>Click me</SlButton>

However, this does not work for me.

KonnorRogers Jul 3, 2024
Maintainer

Why do Shoelace components not need client:load like framework components?

They do if you get SSR to work. Those client directives are for server-rendered components and specify how they should be hydrated on the client.

Right now, I (and you too) only get the Shoelace components to work on the client - without any actual render on the server. You can see that when you throttle your network speed in the dev tools or deactivate JS. Then sl-button is rendered like a unknown HTML tag (like a div) until the JS portion is loaded on the client, then it renders the sl-button element accordingly. This is exactly why you have to import those components in a script block - so that they're available on the client (that's basically a global import).

What my (and probably your) goal is: SSR support. Render the Shoelace button on the server, then hydrate it when necessary (e.g. with client:idle). In that case you would have to use Astro's Lit integration and import it like this:
---
import SlButton from "@shoelace-style/shoelace/dist/components/button/button.js";
---

<SlButton client:idle>Click me</SlButton>
However, this does not work for me.

Correct. SSR isn't quite supported yet. We have some things to iron out, but this will be the way to use Shoelace + Astro + SSR in the future

b-d-m-p · 2024-07-02T09:31:15Z

b-d-m-p
Jul 2, 2024
Author

I still have some questions that I don't have an answer to, but I made a starter https://github.com/b-d-m-p/astro-shoelace-starter-kit-blog. It is not official, but it works and is probably what most people looking to use.

I also made a tutorial for the docs, which I've submitted as a PR. #2098

Hope it helps someone.

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Shoelace / Astro best practices #2056

{{title}}

Replies: 4 comments 6 replies

{{title}}

{{editor}}'s edit

{{editor}}'s edit

5. Bonus: what javascript would cause the background transitions to stop working?

{{title}}

{{title}}

3. Should shoelace be imported in one import or individually?

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

Select a reply

Shoelace / Astro best practices #2056

b-d-m-p Jun 9, 2024

1. Why do you not have to import Shoelace components, like you would in React?

2. Why do Shoelace components not need client:load like framework components?

3. Should shoelace be imported in one import or individually?

4. Where should Shoelace components be imported in Astro?

5. Bonus: what javascript would cause the background transitions to stop working?

Replies: 4 comments · 6 replies

b-d-m-p Jun 11, 2024 Author

5. Bonus: what javascript would cause the background transitions to stop working?

b-d-m-p Jun 11, 2024 Author

b-d-m-p Jun 11, 2024 Author

3. Should shoelace be imported in one import or individually?

b-d-m-p Jun 11, 2024 Author

b-d-m-p Jul 2, 2024 Author

b2m9 Jul 1, 2024

b-d-m-p Jul 2, 2024 Author

b2m9 Jul 2, 2024

KonnorRogers Jul 3, 2024 Maintainer

b-d-m-p Jul 2, 2024 Author

b-d-m-p
Jun 9, 2024

2. Why do Shoelace components not need `client:load` like framework components?

Replies: 4 comments 6 replies

b-d-m-p
Jun 11, 2024
Author

b-d-m-p Jun 11, 2024
Author

b-d-m-p
Jun 11, 2024
Author

b-d-m-p Jun 11, 2024
Author

b-d-m-p Jul 2, 2024
Author

b2m9
Jul 1, 2024

b-d-m-p Jul 2, 2024
Author

KonnorRogers Jul 3, 2024
Maintainer

b-d-m-p
Jul 2, 2024
Author