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-shimVerified import paths — ran on the pinned version, not inferred.
Demonstrates how to import and verify server-side DOM APIs like `HTMLElement` and `customElements` are available, preventing common SSR errors without full browser emulation.
Do not expect browser-like rendering or interactive DOM behavior from this package. For full DOM emulation, consider JSDOM.
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.
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.
Install `server-dom-shim` and import the necessary DOM APIs, ensuring your SSR entry point runs after the shim has been loaded.
Ensure you are using `import { HTMLElement } from 'server-dom-shim';` for ESM projects. `server-dom-shim` is designed for ESM usage.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.