WebUI Native Node Module Handler #

The @microsoft/webui npm package provides high-performance server-side rendering for Node.js / Bun / Deno. It uses a native addon with zero-copy Buffer access and streams rendered HTML fragments via callbacks for progressive rendering with minimal latency.

Installation #

npm install @microsoft/webui

Examples #

Node.jsBunDeno
import { createServer } from 'node:http';
import { readFileSync } from 'node:fs';
import { renderStream } from '@microsoft/webui';

const protocol = readFileSync('./dist/protocol.bin');

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

server.listen(3000);
import { render } from '@microsoft/webui';

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

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

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

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

API Reference #

FunctionDescription
build(options)Build templates into a protocol. Returns { protocol, cssFiles, stats }
render(protocol, state, options?)Render protocol with route matching. Returns the rendered HTML as a string
renderStream(protocol, state, onChunk, options?)Render with streaming output. Each HTML fragment is passed to onChunk as it is produced
inspect(protocol)Convert protocol to JSON for debugging

RenderOptions #

FieldTypeDefaultDescription
entrystring"index.html"Fragment ID to start rendering from
requestPathstring"/"URL path to match routes against
pluginstring-Handler plugin name (see Plugins)

state accepts either an object (auto-serialized) or a pre-stringified JSON string.

BuildOptions #

FieldTypeDefaultDescription
appDirstring-Path to app folder
entrystring"index.html"Entry file
css"link" | "style" | "module""link"CSS delivery strategy
dom"shadow" | "light""shadow"DOM strategy for component rendering
pluginstring-Parser plugin name (see Plugins for the available identifiers)
componentsstring[]-External component sources

BuildStats #

FieldTypeDescription
durationMsnumberBuild time in milliseconds
fragmentCountnumberTotal fragments
componentCountnumberComponents registered
cssFileCountnumberCSS files produced
protocolSizeBytesnumberProtocol binary size
tokenCountnumberCSS tokens discovered