Server-Side Rendering with knitkit Node Loader

Use @knitkit/node to load federated modules in Node.js via module.register loader hooks, with SRI verification and hydration-parity import maps.

@knitkit/node brings the same manifest-driven federation to your Node.js server. It installs module.register loader hooks so that bare specifiers you negotiate in an import map resolve to remote ESM modules fetched over HTTP — exactly the same modules the browser loads. Before executing any remote file, the loader verifies its sha384 integrity hash. After rendering, serializeImportMap emits a <script type="importmap"> tag with browser URLs so the client hydrates against the same dependency versions the server used — no dual-React, no hydration mismatch.

Install

npm i @knitkit/node

How it works

registerFederation(importMap) calls Node’s built-in module.register to install a pair of loader hooks (resolve + load) on a worker thread. From that point forward, any import() call whose specifier appears in the map’s "imports" object resolves through the map — just like the browser does. Relative imports inside a remote module resolve against the remote’s own URL, so the remote’s full dependency graph loads over the network automatically.

The import map you pass to registerFederation is typically the one produced by negotiateShared (re-exported from @knitkit/node), which means the server and browser negotiate from the same manifest and arrive at the same winner for every shared package.

Call registerFederation before importing any module that must resolve through the map. Node’s loader hooks take effect for imports made after the call returns; earlier imports are already resolved and cannot be redirected.

Step-by-step setup

SRI verification

Every remote module the loader fetches is checked against its sha384 integrity hash before Node evaluates it. The hash comes from the integrity field of the import map, keyed by the resolved URL (or the bare specifier). If the fetched content does not match, the loader throws with code KNIT_ERR_SRI_MISMATCH and refuses to execute the file.

// Pass integrity hashes alongside the import map.
registerFederation({
  imports: {
    "widgets/Greeting": "https://cdn.example.com/widgets/Greeting.js",
  },
  integrity: {
    "widgets/Greeting": "sha384-<base64hash>",
  },
});

// If the remote file has been tampered with, the import throws:
// Error: Integrity check failed for https://cdn.example.com/widgets/Greeting.js:
//   expected sha384-<base64hash>, got sha384-<actual>.
//   The remote asset does not match its pinned hash — refusing to execute it.
// error.code === "KNIT_ERR_SRI_MISMATCH"

knitkit build writes sha384 hashes for every expose into knit.manifest.json automatically, so you get SRI protection without any manual hashing.

Module cache

The loader hooks run on a Node worker thread and carry measurable per-import overhead. ModuleCache (exported from @knitkit/node) stores fetched and SRI-verified module source in memory keyed by resolved URL, so repeated SSR render paths pay the network and verification cost only once per process lifetime.

import { ModuleCache } from "@knitkit/node";

const cache = new ModuleCache();
// cache.get(url)    — retrieve a cached entry
// cache.set(url, { source, format: "module", integrity })
// cache.has(url)
// cache.delete(url)
// cache.clear()
// cache.size

The hooks bundle their own internal ModuleCache instance automatically. Export your own instance only when you need to pre-warm, introspect, or selectively invalidate cache entries.

Full server entry example

The following is drawn from the examples/node-ssr example in the knitkit repo. It shows the complete flow: fetch manifest, install hooks, render with react-dom/server, serialize the import map, and return HTML.

// server/render.mjs
import { createRequire } from "node:module";
import { pathToFileURL } from "node:url";
import { createElement } from "react";
import { renderToString } from "react-dom/server";
import { registerFederation, serializeImportMap } from "@knitkit/node";

const require = createRequire(import.meta.url);
const reactFile = pathToFileURL(require.resolve("react")).href;

export async function setupRenderer(remoteBase) {
  const manifestUrl = `${remoteBase}/knit.manifest.json`;
  const res = await fetch(manifestUrl);
  if (!res.ok) throw new Error(`Failed to fetch manifest: HTTP ${res.status}`);
  const manifest = await res.json();
  const baseUrl = res.url;

  const decl = manifest.exposes["./Greeting"];
  const remoteUrl = new URL(decl.url, baseUrl).href;

  // Server map: react → local file (shares the instance with react-dom/server).
  // The remote module is SRI-pinned via the integrity field.
  registerFederation({
    imports: { react: reactFile, "widgets/Greeting": remoteUrl },
    integrity: decl.integrity ? { "widgets/Greeting": decl.integrity } : undefined,
  });

  const Greeting = (await import("widgets/Greeting")).default;

  // Browser map: CDN URLs so the client hydrates with the same versions.
  const head = serializeImportMap({
    imports: {
      react:              "https://esm.sh/react@18.3.1",
      "react-dom":        "https://esm.sh/react-dom@18.3.1",
      "react-dom/client": "https://esm.sh/react-dom@18.3.1/client",
      "widgets/Greeting": remoteUrl,
    },
  });

  function renderHtml(props = { name: "world" }) {
    const appHtml = renderToString(createElement(Greeting, props));
    return `<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <title>knitkit — SSR</title>
  ${head}
</head>
<body>
  <div id="root">${appHtml}</div>
  <script type="module">
    import { hydrateRoot } from "react-dom/client";
    import { createElement } from "react";
    const Greeting = (await import("widgets/Greeting")).default;
    hydrateRoot(
      document.getElementById("root"),
      createElement(Greeting, ${JSON.stringify(props)}),
    );
  </script>
</body>
</html>`;
  }

  return { renderHtml };
}

renderToString is used here for simplicity. react-dom/server’s streaming APIs (renderToPipeableStream, renderToReadableStream) drop in the same way — registerFederation and serializeImportMap are rendering-strategy agnostic.

Programmatic vs. --import bootstrap

If you prefer not to call registerFederation in code, you can supply the import map via environment variable and use the --import flag:

FEDKIT_IMPORT_MAP_JSON='{"imports":{"react":"file:///...","widgets/Greeting":"https://..."}}' \
  node --import @knitkit/node/register server.mjs

@knitkit/node/register reads FEDKIT_IMPORT_MAP_JSON (inline JSON) or FEDKIT_IMPORT_MAP (a path to a JSON file) and calls registerFederation before your server entry runs. If neither variable is set, it emits a process warning and skips installation.