nuxt-ssr-lit

A Nuxt3 module for server-side rendering and client-side hydration of Lit custom elements.

🚀 Usage

Note: This module is for Nuxt3. Please see this issue on Nuxt2 support. We are looking for assistance in finishing up the module.

Installation

Install nuxt-ssr-lit.

npx nuxi@latest module add ssr-lit

Add following code to modules section of nuxt.config.js.

import { defineNuxtConfig } from "nuxt";

export default defineNuxtConfig({
  modules: [
    ["nuxt-ssr-lit", { litElementPrefix: ["acme-"] }]
    // ...
  ]
});

That's it! Now all the Lit elements prefixed with acme- will be Server-Side Rendered. If there are any other custom elements in the project they will be client-side rendered.

👨‍💻 Development

• Run npm run dev:prepare to generate type stubs.
• Use npm run dev to start playground in development mode.

Common issues

TypeError: customElements.get(...) is not a constructor

This error occurs when the Lit element is not properly registered. This can happen because the element is not set up correctly, or it can be due to the element having side effects. You may also only see this error when running in production mode.

To fix this, your custom element library can be registered in the nuxt.config.js file.

export default defineNuxtConfig({
  ...
  nitro: {
    moduleSideEffects: ["my-custom-element-library"]
  }
});

How does it work?

All the Lit elements in the Nuxt project that uses the prefix(es) provided in the module option are wrapped with a Vue component called LitWrapper.

This auto-wrapping is done via a Vite Plugin called AutoLitWrapper and therefore happens during build time. By default, the plugin only operates on Vue files, which helps to optimize performance by avoiding unnecessary processing.

So, if there is a Lit element used in one of the components. E.g. <acme-button>Hello world</acme-button>, the code that is actually generated and used by Nuxt/Vue will be <LitWrapper><acme-button>Hello world</acme-button></LitWrapper>.

The LitWrapper component on the server side uses the @lit-labs/ssr's LitElementRenderer to render the wrapped Lit element with Declarative Shadow DOM. This makes the Lit component render properly on the browser without having the JS to load and execute and as soon the server HTML is parsed.

The LitWrapper component on the client side does nothing and let the normal client-side hydration take place.

Caveats

The Lit components are SSR-ed on the Node side by applying a tiny DOM shim to Node. Not all DOM APIs are available. E.g. getting the assigned slots or children, dispatching custom events, adding event listeners on lifecycle hooks that are called on the server-side will not work. Avoiding such client-side activities on server-run code will take you long way.

Also, check the @lit-labs/ssr's library status for more information.