@lit-labs/ssr-dom-shim

What is @lit-labs/ssr-dom-shim?

The @lit-labs/ssr-dom-shim package is designed to provide a server-side DOM shim for use with Lit components, enabling server-side rendering (SSR) of components that normally rely on browser-specific DOM APIs. This package helps in rendering web components on the server, making it easier to build isomorphic applications.

What are @lit-labs/ssr-dom-shim's main functionalities?

DOM Shim for Server-Side Rendering

This feature allows the rendering of Lit HTML templates on the server, using a DOM shim to emulate a browser-like environment. The code sample demonstrates how to render a simple Lit HTML template to a stream, which can then be sent as a response in a server environment.

import { ssr } from '@lit-labs/ssr';
import { html } from 'lit';
import { renderToStream } from '@lit-labs/ssr/lib/render-to-stream.js';

const template = html`<div>Hello, SSR!</div>`;
const resultStream = renderToStream(template);
resultStream.pipe(process.stdout);

Other packages similar to @lit-labs/ssr-dom-shim

domino

Domino is a server-side DOM implementation based on Mozilla's dom.js, allowing Node.js applications to implement parts of the web platform DOM. This is similar to @lit-labs/ssr-dom-shim in that it provides DOM APIs on the server, but it is more general-purpose and not specifically tailored for Lit components.

jsdom

jsdom is another popular server-side DOM implementation that simulates a web browser's environment. Like @lit-labs/ssr-dom-shim, jsdom allows the manipulation of the structure and contents of web pages using standard DOM API. However, jsdom is more comprehensive and includes support for a wider range of web standards, making it suitable for testing and scraping applications beyond just rendering components.

README

@lit-labs/ssr-dom-shim

Overview

This package provides minimal implementations of Element, HTMLElement, EventTarget, Event, CustomEvent, CustomElementRegistry, and customElements, designed to be used when Server Side Rendering (SSR) web components from Node, including Lit components.

Usage

Usage from Lit

Lit itself automatically imports these shims when running in Node, so Lit users should typically not need to directly depend on or import from this package.

See the lit.dev SSR docs for general information about server-side rendering with Lit.

Usage in other contexts

Other libraries or frameworks who wish to support SSR are welcome to also depend on these shims. (This package is planned to eventually move to @webcomponents/ssr-dom-shim to better reflect this use case). There are two main patterns for providing access to these shims to users:

1. Assigning shims to globalThis, ensuring that assignment occurs before user-code runs.

2. Importing shims directly from the module that provides your base class, using the node export condition to ensure this only happens when running in Node, and not in the browser.

Lit takes approach #2 for all of the shims except for customElements, Event and CustomEvent, so that users who have imported lit are able to call customElements.define or new Event(...)/new CustomEvent(...) in their components from Node.

Exports

The main module exports the following values. Note that no globals are set by this module.

• EventTarget
  • addEventListener
  • dispatchEvent
  • removeEventListener
• Element
  • (Inherits from EventTarget)
  • attachShadow
  • shadowRoot
  • attributes
  • hasAttribute
  • getAttribute
  • setAttribute
  • removeAttribute
• HTMLElement
  • (Inherits from Element)
• CustomElementRegistry
• customElements
• Event
• CustomEvent

Contributing

Please see CONTRIBUTING.md.