Light Dark System

Integrating with Astro

This page explains how to integrate Cordwainer Elements with an Astro app.

SSR and client scripts

In the following tutorial you will notice that Cordwainer Elements cannot be imported in the frontmatter of Astro files. This is because Cordwainer Elements relies on globals from the DOM to be present.

There is a Lit + Astro integration for SSR , however it will not work with Cordwainer Elements 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
  • Cordwainer Elements: 1.0.0

To get started using Cordwainer Elements with Astro, the following packages must be installed.

npm install @cordwainer/cw-elements rollup-plugin-copy

Importing components

In /src/pages/index.astro, set the base path and import Cordwainer Elements.

---
// import default stylesheet
import "@cordwainer/cw-elements/dist/themes/light.css";
---

<html>
  <body>
    <cw-button>Button</cw-button>
  </body>
</html>

<script>
  // setBasePath to tell Cordwainer Elements where to load icons from.
  import { setBasePath } from '@cordwainer/cw-elements/dist/utilities/base-path.js';
  setBasePath('/cw-assets/');

  // Load all components.
  import '@cordwainer/cw-elements';
</script>

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 Cordwainer Elements import.

---
import { setBasePath } from "@cordwainer/cw-elements/dist/utilities/base-path.js";
setBasePath("dist/assets");
---

<html>
  <body>
    <cw-tooltip content="This is a tooltip">
      <cw-button>Hover Me</cw-button>
    </cw-tooltip>
  </body>
</html>

<script>
  // setBasePath to tell Cordwainer Elements where to load icons from.
  import { setBasePath } from '@cordwainer/cw-elements/dist/utilities/base-path.js';
  setBasePath('/cw-assets/');

  // Load all components.
  import '@cordwainer/cw-elements';

  const duration = 3000;
  import { setDefaultAnimation } from '@cordwainer/cw-elements/dist/utilities/animation-registry.js';

  setDefaultAnimation('tooltip.show', {
    keyframes: [
      { opacity: 0, scale: 0.8 },
      { opacity: 1, scale: 1 }
    ],
    options: { duration: duration, easing: 'ease' }
  });
</script>

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 Cordwainer Elements’s assets into your public directory.

Here’s what your Astro config should look like:

// 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/@cordwainer/cw-elements/dist/assets/*', dest: 'public/cw-assets/assets/' }]
      })
    ]
  }
});