@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

$3

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.

$3

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.

$3

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
- MediaList
- StyleSheet
- CSSRule
- CSSRuleList
- CSSStyleSheet
- (Inherits from StyleSheet)
- replace
- replaceSync

$3

@lit-labs/ssr-dom-shim/register-css-hook.js implements/registers a
Node.js customization hook
(Node.js >= 18.6.0) to import CSS files/modules as instances of CSSStyleSheet.

``ts
import styles from 'my-styles.css' with {type: 'css'};
// styles is now an instance of CSSStyleSheet
`

This can either be used as a parameter with the Node.js CLI
(e.g. node --import @lit-labs/ssr-dom-shim/register-css-hook.js my-script.js or via
environment variable NODE_OPTIONS="--import @lit-labs/ssr-dom-shim/register-css-hook.js")
or imported inline, and it will apply to any module dynamically imported afterwards
(e.g. import @lit-labs/ssr-dom-shim/register-css-hook.js and
subsequently await import('./my-component.js')`).

- Node.js Customization Hooks
- Import Attributes

Contributing

Please see CONTRIBUTING.md.