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.
@lit-labs/ssr-dom-shim
Overview
This package provides minimal implementations of Element
, HTMLElement
,
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:
-
Assigning shims to globalThis
, ensuring that assignment occurs before
user-code runs.
-
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
, so that
users who have imported lit
are able to call customElements.define
in their
components from Node.
Exports
The main module exports the following values. Note that no globals are set by
this module.
Contributing
Please see CONTRIBUTING.md.