WebUI Native Node Module Handler #

The @microsoft/webui npm package provides high-performance server-side rendering for Node.js, Bun, and Deno. It uses a native addon with a canonical UTF-8 Buffer path plus batched callbacks for streaming responses.

Installation #

npm install @microsoft/webui

Examples #

import { createServer } from 'node:http';
import { readFileSync } from 'node:fs';
import { Protocol } from '@microsoft/webui';

const protocol = new Protocol(
  readFileSync('./dist/protocol.bin'),
  { plugin: 'webui' },
);

const server = createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/html' });
  protocol.renderStream(
    { title: 'Home' },
    (chunk) => res.write(chunk),
    { entry: 'index.html', requestPath: req.url },
  );
  res.end();
});

server.listen(3000);

import { Protocol } from '@microsoft/webui';

const protocol = Bun.file('./dist/protocol.bin');
const protocolData = Buffer.from(await protocol.arrayBuffer());
const runtimeProtocol = new Protocol(protocolData);

Bun.serve({
  port: 3000,
  fetch(req) {
    const url = new URL(req.url);
    const html = runtimeProtocol.render({ title: 'Home' }, {
      entry: 'index.html',
      requestPath: url.pathname,
    });
    return new Response(html, {
      headers: { 'Content-Type': 'text/html' },
    });
  },
});

import { Protocol } from '@microsoft/webui';

const protocol = Deno.readFileSync('./dist/protocol.bin');
const protocolData = Buffer.from(protocol);
const runtimeProtocol = new Protocol(protocolData);

Deno.serve({ port: 3000 }, (req) => {
  const url = new URL(req.url);
  const html = runtimeProtocol.render({ title: 'Home' }, {
    entry: 'index.html',
    requestPath: url.pathname,
  });
  return new Response(html, {
    headers: { 'Content-Type': 'text/html' },
  });
});

API Reference #

RenderOptions #

ProtocolOptions #

Reusing Protocol #

Load protocol.bin once and construct one Protocol for the lifetime of the server:

const protocol = new Protocol(
  readFileSync('./dist/protocol.bin'),
  { plugin: 'webui' },
);

const server = createServer((req, res) => {
  const html = protocol.render(getState(req), {
    entry: 'index.html',
    requestPath: req.url,
  });
  res.end(html);
});

Protocol owns the decoded native state, deterministic index, and template metadata cache. The source Buffer can be released or reused after construction. The package has no hidden WeakMap, protocol-sized mutation snapshot, or render path that accepts protocol bytes on every request.

protocol.render() returns a UTF-8 Buffer so the native allocation can be passed directly to response.end(). Call .toString('utf8') only when JavaScript string operations are required. Use protocol.renderStream() when the HTTP integration can make progress from callbacks; callbacks are batched rather than invoked for every internal handler write. The callback is synchronous and its return value is ignored. A false result from response.write() cannot pause native rendering or wait for drain, so this API does not provide transport backpressure. Callback exceptions abort the render immediately and propagate to the caller.

Reusing immutable state #

When one state snapshot is rendered more than once, prepare it alongside the protocol:

const cachedState = protocol.prepareState(await loadCatalogState());

const server = createServer((_req, res) => {
  res.end(protocol.renderPrepared(cachedState));
});

Preparation performs serialization and native JSON parsing once. renderPrepared() reuses the immutable native tree and produces the same bytes as render() for matching options. Later mutations to the source object are not visible; create a new prepared state when request data changes.

The opaque handle is process-local and cannot be serialized. It retains the native state tree until JavaScript garbage collection releases the handle, so this API trades resident native memory for lower repeated-render CPU and allocation pressure. Ordinary per-request state should continue to use render().

BuildOptions #

Unwrapped components default to generated open Shadow roots. Set dom: "light" to make them global Light DOM; authored sole open Shadow roots remain Shadow. Light CSS uses ordinary selectors, and :host, :host-context, and ::slotted fail with unsupported-light-css.

const result = build({
  appDir: './src',
  plugin: 'webui',
  projectionManifests: ['./dist/webui-projection.json'],
});

When componentAssetRoots contains multiple roots, the build returns a version 2 asset graph in componentAssetFiles: entry-reachable dependencies stay external, single-root dependencies stay inline, and dependencies with the same multi-root consumer set are emitted once as shared chunks. Asset-only records are removed from result.protocol. Component assets cannot be combined with <route>.

Set metafile: true to receive result.metafile. The JSON uses esbuild's inputs/outputs schema, root entryPoint records, and dynamic-import edges, so it can be opened directly in an esbuild bundle analyzer.

Manifest inputs are build-time only. The returned protocol is self-contained, and render() does not load projection tooling. If no manifest is supplied, the build preserves full state.

The Node API requires the platform-specific native addon. Addon resolution and loading errors are returned directly and never trigger a CLI subprocess. Use the webui CLI explicitly when a filesystem-oriented build is preferred.

BuildStats #

Progressive Streaming #

renderStream() is push-based: the native renderer decides when your callback runs, so a false result from response.write() cannot pause it. That is fine for whole-document rendering, but it cannot express a response your server paces.

protocol.streamResponse() inverts that. It opens a session whose methods return bytes, so your server owns the socket and backpressure:

const session = protocol.streamResponse({
  entry: 'index.html',
  requestPath: '/',
});

res.writeHead(200, {
  'Content-Type': 'text/html; charset=utf-8',
  'X-Accel-Buffering': 'no',
});

let step = session.start(initialState);
await write(res, step.bytes);

while (!step.done) {
  const boundary = step.boundary;
  if (boundary) {
    const state = await loadBoundaryState(
      boundary.owner,
      boundary.name,
      boundary.key,
    );
    step = session.resume(boundary.instanceId, state, 'final');
  } else {
    step = session.advance();
  }
  await write(res, step.bytes);
}
res.end();

async function write(res, chunk) {
  if (res.write(chunk)) return;
  // An aborted client never emits 'drain', and surfaces as 'close', not
  // 'error' — so waiting on 'drain' alone would hang forever.
  await new Promise((ok, fail) => {
    const done = (error) => {
      res.off('drain', onDrain);
      res.off('close', onClose);
      if (error) fail(error);
      else ok();
    };
    const onDrain = () => done();
    const onClose = () => done(new Error('client disconnected'));
    res.once('drain', onDrain);
    res.once('close', onClose);
  });
}

The same shape works behind Express, Fastify, Hapi, or a raw socket. Boundaries are discovered at runtime through entries, reusable components, conditions, and the selected route. A boundary-bearing subtree under <for> fails the build with boundary-in-repeat; a whole <for> may sit inside one boundary.

StreamingSession #

A descriptor contains instanceId, declarationId, owner, name, and an optional string or numeric key. Use those fields to load state, then pass instanceId back to resume. A descriptor means call resume; no descriptor with done: false means call advance; done: true means complete.

resume is boundary-only so its bytes can be written and flushed without waiting for following parent content. advance carries that parent content and the document tail. No sibling boundary workaround is needed. The final step already contains tail and terminal bytes. mode is "final" by default or "updatable".

An update never inserts markup or reruns hydration:

const patch = session.update(searchInstanceId, { query: 'webui' });
await write(res, patch);

An update may be written between the occurrence's resume and advance. Sessions are single-driver and independent. Hold one per in-flight request and stop driving it after a rendering or transport failure.