@semantic-org/astro-lit

The official @astrojs/lit integration was deprecated in Astro v5. This community-maintained integration enables you to continue using Lit with modern versions of Astro.

This Astro integration enables server-side rendering and client-side hydration for your Lit custom elements.

Features

• Server-side rendering (SSR) of Lit components.
• Client-side hydration with Astro client:* directives.
• Automatic polyfills for Declarative Shadow DOM in unsupported browsers.
• Support for experimental decorators.

Installation

Prerequisites

• Astro v5.0 or later.
• Node.js v18.17.1, v20.3.0 or later.

To use the Lit integration, you first install the required package and then update your Astro configuration.

Procedure

1. Install the integration package into your project:

   • npm

     $ npm install @semantic-ui/astro-lit

   • pnpm

     $ pnpm add @semantic-ui/astro-lit

   • yarn

     $ yarn add @semantic-ui/astro-lit

2. Update your astro.config.mjs file to include the Lit integration.

   import { defineConfig } from 'astro/config';
   import lit from '@semantic-ui/astro-lit';
   
   export default defineConfig({
     integrations: [lit()],
   });

Usage

To learn about using framework components in Astro, refer to the Astro Framework Components guide.

Creating and Using a Lit Component

To use a Lit component, create a component file and then import it into your .astro pages.

1. Create your Lit component. For example, create a new file named my-element.js in the src/components/ directory.

   import { LitElement, html } from 'lit';
   
   export class MyElement extends LitElement {
     render() {
       return html`<p>Hello world! This is my Lit component.</p>`;
     }
   }
   
   customElements.define('my-element', MyElement);

2. Import and use the component in an Astro page. Note that Astro requires you to use the class name, MyElement, as the component tag, not the custom element tag name my-element.

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

Using Third-Party Lit Components

You can also use third-party web components that are built with Lit. To use a third-party component, import its JavaScript module, which typically registers the custom element as a side effect. Then, you can use the custom element tag directly in your template.

In the following example, you import a third-party button component and use it with its custom HTML tag, <sbb-button>:

---
// This import registers the <sbb-button> custom element.
import '@sbb-esta/lyne-elements/button.js';
---
<h1>Third-Party Component Example</h1>

<sbb-button>Click Me</sbb-button>

Client-Side Hydration

To hydrate a component on the client, add an Astro client:* directive. These directives determine when the component's JavaScript is sent to the browser.

For example, to hydrate a component only when it becomes visible in the viewport, use the client:visible directive:

---
import { MyElement } from '../components/my-element.js';
---
<MyElement client:visible />

For a full list of available directives, refer to the official Astro Client Directives documentation.

Using Experimental Decorators

To use experimental decorators in Lit, for example @customElement or @state, you must enable the experimentalDecorators option in your tsconfig.json file.

1. If you do not have one, create a tsconfig.json file in the root of your project.

2. Add the compilerOptions.experimentalDecorators setting:

   {
     "compilerOptions": {
       "experimentalDecorators": true
     }
   }

You can now use decorators in your Lit TypeScript components:

import { LitElement, html } from "lit";
import { customElement, property } from "lit/decorators.js";

@customElement("my-decorator-element")
export class MyDecoratorElement extends LitElement {
    @property()
    name = "World";

    override render() {
        return html`<p>Hello, ${this.name}!</p>`;
    }
}

Troubleshooting

This section describes common issues and their solutions.

Browser Global Interference

The Lit integration adds browser global properties, for example window and document, to the global scope during server-side rendering. These globals can interfere with other libraries that check for their existence to determine if they are running in a browser environment. This can cause unexpected behavior or errors with other libraries.

If you use multiple integrations, changing their order in the astro.config.mjs file can sometimes resolve the issue.

import { defineConfig } from 'astro/config';
import vue from '@astrojs/vue';
import lit from '@semantic-ui/astro-lit';

export default defineConfig({
  // If vue() causes issues, try placing lit() before it.
  integrations: [lit(), vue()]
});

Component Not Updating in Development

During development, if you make changes to a Lit component and do not see the updates in your browser, you might need to restart the Astro development server.

Strict Package Manager Errors

When you use a strict package manager like pnpm, you can encounter a ReferenceError: module is not defined error. To resolve this, create a .npmrc file in your project's root directory and add a hoist pattern for Lit dependencies:

public-hoist-pattern[]=*lit*

Contributing

This project is open source and maintained by the community. You are welcome to submit issues and pull requests.

• To report a bug or request a feature, open an issue.
• To contribute code, please open a pull request.

License

MIT