From e1bd1fe790089e598018a924a4e7a48d0ae844c6 Mon Sep 17 00:00:00 2001 From: Brett Peary Date: Thu, 11 Jul 2024 00:22:44 +0900 Subject: [PATCH] Add astro tutorial (#2098) * Add astro tutorial * Added Astro tutorial link to sidebar nav * Update docs/pages/tutorials/integrating-with-astro.md Co-authored-by: Konnor Rogers * Update docs/pages/tutorials/integrating-with-astro.md Move import into index Co-authored-by: Konnor Rogers * Update docs/pages/tutorials/integrating-with-astro.md Remove setBasePath from frontmatter imports Co-authored-by: Konnor Rogers * Update docs/pages/tutorials/integrating-with-astro.md Add ssr & client scripts section Co-authored-by: Konnor Rogers * Update docs/pages/tutorials/integrating-with-astro.md add rollup-plugin-copy to npm install command Co-authored-by: Konnor Rogers * Update docs/pages/tutorials/integrating-with-astro.md Move setBasePath to script tag Co-authored-by: Konnor Rogers * Update docs/pages/tutorials/integrating-with-astro.md Add explanation for addition of rollup-plugin-copy Co-authored-by: Konnor Rogers * Update docs/pages/tutorials/integrating-with-astro.md Co-authored-by: Konnor Rogers --------- Co-authored-by: Konnor Rogers --- docs/_includes/sidebar.njk | 1 + .../pages/tutorials/integrating-with-astro.md | 131 ++++++++++++++++++ 2 files changed, 132 insertions(+) create mode 100644 docs/pages/tutorials/integrating-with-astro.md diff --git a/docs/_includes/sidebar.njk b/docs/_includes/sidebar.njk index ed4a6710..11745e65 100644 --- a/docs/_includes/sidebar.njk +++ b/docs/_includes/sidebar.njk @@ -57,6 +57,7 @@

  • Tutorials

      +
    • Integrating with Astro
    • Integrating with Laravel
    • Integrating with NextJS
    • Integrating with Rails
      • diff --git a/docs/pages/tutorials/integrating-with-astro.md b/docs/pages/tutorials/integrating-with-astro.md new file mode 100644 index 00000000..186e46eb --- /dev/null +++ b/docs/pages/tutorials/integrating-with-astro.md @@ -0,0 +1,131 @@ +--- +meta: + title: Integrating with Astro + description: This page explains how to integrate Shoelace with an Astro app. +--- + +# Integrating with Astro + +This page explains how to integrate Shoelace with an Astro app. + +:::tip +This is a community-maintained document. Please [ask the community](/resources/community) if you have questions about this integration. You can also [suggest improvements](https://github.com/shoelace-style/shoelace/blob/next/docs/tutorials/integrating-with-astro.md) to make it better. +::: +## SSR and client scripts + +In the following tutorial you will notice that Shoelace cannot be imported in the frontmatter of Astro files. This is because Shoelace relies on globals from the DOM to be present. + +There is a [Lit + Astro integration for SSR](https://docs.astro.build/en/guides/integrations-guide/lit/) , however it will not work with Shoelace in its current state due to some reliance on DOM APIs that aren't shimmed. We are working to resolve this. +## Instructions - Astro 4.11.3 + +- Node: v18.17.1 or v20.3.0 or higher. ( v19 is not supported.) +- Astro: 4.11.3 +- Shoelace: 2.15.1 + +To get started using Shoelace with Astro, the following packages must be installed. + +```bash +npm install @shoelace-style/shoelace rollup-plugin-copy +``` + + + +### Importing components + +In `/src/pages/index.astro`, set the base path and import Shoelace. + +```html +--- +// import default stylesheet +import "@shoelace-style/shoelace/dist/themes/light.css"; +--- + + + + Button + + + + + +``` + +:::tip +If you want to cherry pick components, replace the main Shoelace import with 'import "@shoelace-style/shoelace/dist/components/button/button.js";' for whichever component you would like. +::: + +You only have to import in the main `index.astro` file. The components can be used anywhere throughout the project. + +### Customizing animations + +In `/src/pages/index.astro`, set custom animations after the Shoelace import. + +```html +--- +import { setBasePath } from "@shoelace-style/shoelace/dist/utilities/base-path.js"; +setBasePath("dist/assets"); +--- + + + + + Hover Me + + + + + + +``` +## Modifying Astro Config + +You'll notice the above steps never added our icons into our `/public` directory. To solve this, we can install `rollup-plugin-copy` to copy Shoelace's assets into your public directory. + +Here's what your Astro config should look like: + +```js +// astro.config.mjs + +import { defineConfig } from 'astro/config'; +import copy from 'rollup-plugin-copy' + +// https://astro.build/config +export default defineConfig({ + vite: { + plugins: [ + copy({ + // Copy only on first build. We dont want to trigger additional server reloads. + copyOnce: true, + hook: "buildStart", + targets: [ + { src: 'node_modules/@shoelace-style/shoelace/dist/assets/*', dest: 'public/shoelace-assets/assets/' }, + ] + }) + ] + } +});