Registry / web-framework / server-dom-shim

server-dom-shim

JSON →
library1.1.0jsnpmunverified

server-dom-shim is a utility package designed to provide a minimal shim for standard DOM APIs within server-side rendering (SSR) environments. Its primary purpose is to prevent common errors like `HTMLElement is not defined` when rendering web components or other DOM-dependent JavaScript on the server, without incurring the overhead of a full browser emulation library like JSDOM. The package is currently at version 1.1.0 and has seen a consistent, albeit not rapid, release cadence with updates in late 2025 and mid-2024. A key differentiator is its use of Node.js conditional exports, which intelligently exports `@lit-labs/ssr-dom-shim` in Node.js environments while deferring to native DOM APIs in browser contexts. This approach allows developers to write universal codebases that seamlessly adapt to different execution environments, making it suitable for modern SSR frameworks and libraries that leverage web standards. It focuses on providing necessary global definitions rather than full interactive DOM capabilities.

npm install server-dom-shim
INSTALL
IMPORT
SIG · SERVER-DOM-SHIM
S
server-dom-shim
web-frameworkjavascriptv1.1.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

HTMLElement
import { HTMLElement } from 'server-dom-shim'
const { HTMLElement } = require('server-dom-shim')
The package primarily uses ESM imports. CommonJS `require` is not supported for named exports and can lead to `undefined` or `TypeError`.
customElements
import { customElements } from 'server-dom-shim'
const { customElements } = require('server-dom-shim')
This provides a shimmed `CustomElementRegistry` instance for defining custom elements on the server, preventing `ReferenceError`.
Event
import { Event, CustomEvent } from 'server-dom-shim'
import Event from 'server-dom-shim'
Common DOM event constructors are exposed as named exports. There is no default export.

Demonstrates how to import and verify server-side DOM APIs like `HTMLElement` and `customElements` are available, preventing common SSR errors without full browser emulation.

import { HTMLElement, customElements, Event, CustomEvent, Element } from 'server-dom-shim'; // Verify that HTMLElement is defined in the server environment console.log('HTMLElement is defined:', typeof HTMLElement !== 'undefined'); // Example: Define a simple custom element (though it won't render visually in Node.js) class MyCustomElement extends HTMLElement { constructor() { super(); // In a real SSR scenario, this would be part of a component's lifecycle // and prevent errors when a framework tries to instantiate it. console.log('MyCustomElement instance created (server-side shim)'); } connectedCallback() { console.log('MyCustomElement connectedCallback (server-side shim)'); } } // Define the custom element if not already defined (important for re-runs in dev) if (!customElements.get('my-custom-element')) { customElements.define('my-custom-element', MyCustomElement); console.log('Custom element "my-custom-element" defined (server-side shim)'); } // Example: Create an event instance const myEvent = new CustomEvent('my-custom-event', { detail: { data: 'hello' } }); console.log(`Created event: ${myEvent.type} with detail:`, myEvent.detail); // This shim allows libraries that expect a DOM environment to run without errors during SSR.
Debug
Known issues
gotchaThis package provides a *shim* for DOM APIs, not a full browser environment. It does not support rendering, layout, or interactive browser-specific functionalities (e.g., `document.body.appendChild()` leading to visual updates). It primarily provides constructors and prototypes to prevent `ReferenceError` during SSR.
fix
Do not expect browser-like rendering or interactive DOM behavior from this package. For full DOM emulation, consider JSDOM.
affects: >=1.0.0
gotchaThe package uses Node.js conditional exports, which means the actual shim (`@lit-labs/ssr-dom-shim`) is only active in Node.js environments. In browser environments, it exports native DOM APIs. This can lead to subtle behavioral differences between environments if not understood.
fix
Be aware that the shim's effects are specific to Node.js contexts. Ensure your universal code correctly handles the native DOM in browsers where the shim is a passthrough.
affects: >=1.0.0
breakingWhile v1.1.0 added comprehensive exports for 'all DOM and CSS APIs', older versions might have had a more limited set of shims. If upgrading from pre-1.1.0 versions, ensure that any previously missing APIs are now correctly shims rather than relying on custom workarounds.
fix
Review your SSR code after updating to v1.1.0+ to leverage the expanded API surface and remove any custom shims that might now be redundant or conflict with the official ones.
affects: >=1.1.0
Errors
Common errors & fixes
ReferenceError: HTMLElement is not defined
Attempting to instantiate or reference `HTMLElement` (or similar DOM globals) in a Node.js environment without a DOM shim.
fix
Install `server-dom-shim` and import the necessary DOM APIs, ensuring your SSR entry point runs after the shim has been loaded.
TypeError: (0, import_server_dom_shim.HTMLElement) is not a constructor (or similar `require` errors in ESM projects)
Attempting to import named exports from `server-dom-shim` using CommonJS `require()` syntax in an ESM project, or vice versa.
fix
Ensure you are using `import { HTMLElement } from 'server-dom-shim';` for ESM projects. `server-dom-shim` is designed for ESM usage.
Cannot find module 'server-dom-shim' (during build with Vite, Rollup, etc.)
Build tools sometimes have issues resolving conditional exports or specific module resolutions, especially in earlier versions of bundlers or specific configurations. Version 1.0.2 explicitly mentions a 'vite build issue workaround'.
fix
Ensure your build tool (e.g., Vite) is updated to a recent version. If the problem persists, check the `server-dom-shim` GitHub issues or documentation for specific build tool configurations, or consider adjusting your bundler's module resolution settings.
Upgrade
Version history
1.1.0latest on npm
Audit
Dependencies
@lit-labs/ssr-dom-shimrequiredUsed internally as the DOM shim implementation when running in Node.js environments.
Agent activity
23 hits · last 30 days
node
22
Resources
server-dom-shim — npm install server-dom-shim · libregistry