Add astro tutorial

[b-d-m-p]

This is a bare-bones Astro explanation of steps to add Shoelace to Astro.

I am sorry for not opening an issue like the community guidelines say to, I just thought as it was a documentation addition there was no issue to write about. If you'd like me to make an issue first, let me know and I will do that. Maybe adding an Astro tutorial is something you're not sure you want to do, but I had chatted with @KonnorRogers and he said he was working on something, so maybe this can help.

The format is based on the Shoelace NextJS tutorial.

Some background information... I had opened a discussion on on using Astro best practices and due to issues I was having, I thought that Astro/Shoelace with Astro's view transitions required a different set up than this bare-bones version, but while making this doc, I made a test project and added view transitions and it works fine, which is great for general users. There must be something wrong with my project.

Let me know if there's any changes I should make.

Cheers

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
shoelace	✅ Ready (Inspect)	Visit Preview	Jul 4, 2024 5:55am

[b-d-m-p]

I made this starter kit, which demos the setup in the tutorial. https://github.com/b-d-m-p/astro-shoelace-starter-kit-blog

[claviska]

Thanks for this! We probably want to add a link in the Tutorials section of the sidebar.

@KonnorRogers I'll defer this one to you, since you have more experience here.

[b-d-m-p]

Oh, I thought the sidebar was auto generated from the files in the folder. If it's manual, I'll add it to the PR.

[b-d-m-p]

It's in there now.

[b2m9]

After I just banged my head against this: can we mention somewhere that SSR is not supported for Shoelace at the moment - hence the script statements on the client.

[KonnorRogers]

After I just banged my head against this: can we mention somewhere that SSR is not supported for Shoelace at the moment - hence the script statements on the client.

I haven't had a chance to actually check if it works, but the Lit SSR module shims the DOM.

https://docs.astro.build/en/guides/integrations-guide/lit/

I know for a fact some components will not render as expected with SSR, and I dont know if any of them will fail with the Lit SSR module

[KonnorRogers]

I ended up making my own Astro setup here and testing out the docs you had and added some suggestions

https://github.com/KonnorRogers/shoelace-astro

My setup was as follows:

npm create astro@latest

[dir]: Where should we create your new project?
         ./shoelace-astro-2
         
  tmpl   How would you like to start your new project?
         ● Include sample files (recommended)
         ○ Use blog template 
         ○ Empty          
 
    ts   Do you plan to write TypeScript?
         ● Yes  ○ No 
         
      use   How strict should TypeScript be?
         ● Strict (recommended)
         ○ Strictest 
         ○ Relaxed 
         
     deps   Install dependencies? (recommended)
         ● Yes  ○ No 


   git   Initialize a new git repository? (optional)
         ● Yes  ○ No 

[b2m9]

I haven't had a chance to actually check if it works, but the Lit SSR module shims the DOM.

Here's a Stackblitz environment for an Astro/Lit integration. Shoelace doesn't fail because of lit-labs/ssr, it seems to fail because it is trying to access the DOM when it's not available (e.g. MutationObserver is not defined). Hence the workaround in the tutorial to load it on the client.

[KonnorRogers]

I haven't had a chance to actually check if it works, but the Lit SSR module shims the DOM.

Here's a Stackblitz environment for an Astro/Lit integration. Shoelace doesn't fail because of lit-labs/ssr, it seems to fail because it is trying to access the DOM when it's not available (e.g. MutationObserver is not defined). Hence the workaround in the tutorial to load it on the client.

Yea there's going to be a number of components that need to be modified to work with Lit's SSR, I'm working on it, but its going to take some time. The Lit SSR module seems to do a very minimal DOM shim only for pieces required for rendering and not for trying to shim the entire DOM.

[b-d-m-p]

@KonnorRogers all your additions are in there now. Thanks! Anything else needed?