dom

@wesc/dom — DOM SSR

@wesc/dom/server renders custom elements on the server via Linkedom. Use it when a component's shadow DOM is built by JavaScript (typically inside connectedCallback) rather than declared in a <template> — the common case for third-party web-component libraries.

It's the DOM-SSR half of WeSC; the ahead-of-time / streaming bundler lives in the wesc package.

Status: pre-1.0 (0.5.x), APIs may change. MIT-licensed. Node-only, requires Node ≥ 18.

Install

npm install @wesc/dom

Entry points

Import	Use
@wesc/dom/server	renderToDom, renderToString, renderToStream, shim.
@wesc/dom/unshim	Restore the global scope after shimming.
@wesc/dom/react	WeSC component + prerender for React/Next.js.
@wesc/dom/astro	Astro integration (addRenderer).

Standalone Node script

index.js

import { promises as fs } from 'fs';
import { renderToString } from '@wesc/dom/server';

// Web components register themselves on import.
import 'media-chrome';

const html = await fs.readFile('./app.html');
const out = await renderToString(html);

await fs.writeFile('./index.html', out);

app.html (trimmed)

<media-controller>
  <video slot="media" playsinline src="https://stream.mux.com/.../high.mp4"></video>
  <media-control-bar>
    <media-play-button></media-play-button>
    <media-time-range></media-time-range>
    <media-fullscreen-button></media-fullscreen-button>
  </media-control-bar>
</media-controller>

renderToString returns a string with the upgraded element trees inlined as Declarative Shadow DOM. View source on the Node example demo to see full output.

Examples

Open an issue if your stack isn't covered.

Framework	Demo	Source
Cloudflare Worker	Demo	Source
Eleventy	Demo	Source
Astro	Demo	Source
Next.js	Demo	Source
SvelteKit	Demo	Source
Remix	Demo	Source
Node	Demo	Source

Develop

npm install           # from the monorepo root
npm test  --workspace=@wesc/dom
npm run build --workspace=@wesc/dom   # bundles src/ into dist/ with esbuild

Related

• Linkedom — DOM implementation powering the SSR path.
• Ocean — web-component server-side rendering.
• WCC — experimental native web components compiler.
• custom-elements-ssr — server-rendering for Lit elements.