{"id":12005,"library":"server-dom-shim","title":"Server-Side DOM Shim","description":"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.","status":"active","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/ocavue/server-dom-shim","tags":["javascript","ssr","html","custom-elements","web-components","node","browser","typescript"],"install":[{"cmd":"npm install server-dom-shim","lang":"bash","label":"npm"},{"cmd":"yarn add server-dom-shim","lang":"bash","label":"yarn"},{"cmd":"pnpm add server-dom-shim","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally as the DOM shim implementation when running in Node.js environments.","package":"@lit-labs/ssr-dom-shim","optional":false}],"imports":[{"note":"The package primarily uses ESM imports. CommonJS `require` is not supported for named exports and can lead to `undefined` or `TypeError`.","wrong":"const { HTMLElement } = require('server-dom-shim')","symbol":"HTMLElement","correct":"import { HTMLElement } from 'server-dom-shim'"},{"note":"This provides a shimmed `CustomElementRegistry` instance for defining custom elements on the server, preventing `ReferenceError`.","wrong":"const { customElements } = require('server-dom-shim')","symbol":"customElements","correct":"import { customElements } from 'server-dom-shim'"},{"note":"Common DOM event constructors are exposed as named exports. There is no default export.","wrong":"import Event from 'server-dom-shim'","symbol":"Event","correct":"import { Event, CustomEvent } from 'server-dom-shim'"}],"quickstart":{"code":"import { HTMLElement, customElements, Event, CustomEvent, Element } from 'server-dom-shim';\n\n// Verify that HTMLElement is defined in the server environment\nconsole.log('HTMLElement is defined:', typeof HTMLElement !== 'undefined');\n\n// Example: Define a simple custom element (though it won't render visually in Node.js)\nclass MyCustomElement extends HTMLElement {\n  constructor() {\n    super();\n    // In a real SSR scenario, this would be part of a component's lifecycle\n    // and prevent errors when a framework tries to instantiate it.\n    console.log('MyCustomElement instance created (server-side shim)');\n  }\n\n  connectedCallback() {\n    console.log('MyCustomElement connectedCallback (server-side shim)');\n  }\n}\n\n// Define the custom element if not already defined (important for re-runs in dev)\nif (!customElements.get('my-custom-element')) {\n  customElements.define('my-custom-element', MyCustomElement);\n  console.log('Custom element \"my-custom-element\" defined (server-side shim)');\n}\n\n// Example: Create an event instance\nconst myEvent = new CustomEvent('my-custom-event', { detail: { data: 'hello' } });\nconsole.log(`Created event: ${myEvent.type} with detail:`, myEvent.detail);\n\n// This shim allows libraries that expect a DOM environment to run without errors during SSR.\n","lang":"typescript","description":"Demonstrates how to import and verify server-side DOM APIs like `HTMLElement` and `customElements` are available, preventing common SSR errors without full browser emulation."},"warnings":[{"fix":"Do not expect browser-like rendering or interactive DOM behavior from this package. For full DOM emulation, consider JSDOM.","message":"This 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"While 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.","severity":"breaking","affected_versions":">=1.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install `server-dom-shim` and import the necessary DOM APIs, ensuring your SSR entry point runs after the shim has been loaded.","cause":"Attempting to instantiate or reference `HTMLElement` (or similar DOM globals) in a Node.js environment without a DOM shim.","error":"ReferenceError: HTMLElement is not defined"},{"fix":"Ensure you are using `import { HTMLElement } from 'server-dom-shim';` for ESM projects. `server-dom-shim` is designed for ESM usage.","cause":"Attempting to import named exports from `server-dom-shim` using CommonJS `require()` syntax in an ESM project, or vice versa.","error":"TypeError: (0, import_server_dom_shim.HTMLElement) is not a constructor (or similar `require` errors in ESM projects)"},{"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.","cause":"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'.","error":"Cannot find module 'server-dom-shim' (during build with Vite, Rollup, etc.)"}],"ecosystem":"npm"}