@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.