@microsoft/webui

High-performance server-side rendering framework. Compiles HTML templates into a binary protocol at build time and renders them with native speed at runtime — no JavaScript runtime overhead.

Installation

npm install @microsoft/webui

The package automatically installs the correct platform-specific native binary for your OS and architecture (Windows, macOS, Linux — x64 and arm64).

Quick start

import { build, render } from "@microsoft/webui";

// Build templates into a protocol
const result = build({ appDir: "./src" });

// Render with state data
const html = render(result.protocol, { name: "World", items: ["a", "b"] });
console.log(html);

API

build(options: BuildOptions): BuildResult

Compiles an application directory of HTML templates into a binary protocol.

const result = build({
  appDir: "./src",        // Path to the template directory
  entry: "index.html",   // Entry file (default: "index.html")
  css: "link",           // CSS strategy: "link" or "style"
  plugin: "fast",        // Parser plugin (e.g., "fast" for FAST-HTML)
  components: [],        // Additional component sources
  outDir: "./dist",      // Output directory for CLI fallback
});

// result.protocol  — Buffer containing the compiled protocol
// result.cssFiles  — Array of [filename, content, ...] pairs
// result.stats     — { durationMs, fragmentCount, componentCount, cssFileCount, protocolSizeBytes, tokenCount }

render(protocol: Buffer, state: object | string): string

Renders a compiled protocol with state data and returns the full HTML string.

const html = render(protocol, { title: "Hello", show: true });

renderStream(protocol: Buffer, state: object | string, onChunk: (html: string) => void): void

Renders with streaming output — each HTML fragment is passed to the callback as it is produced.

renderStream(protocol, state, (chunk) => {
  response.write(chunk);
});

buildAndRender(options: BuildOptions, state: object | string): string

Convenience function that builds and renders in a single call.

const html = buildAndRender({ appDir: "./src" }, { name: "WebUI" });

inspect(protocol: Buffer): string

Returns a JSON representation of the protocol for debugging.

const json = inspect(protocol);
console.log(JSON.parse(json));

renderPartial(protocol: Buffer, stateJson: string, entryId: string, requestPath: string, inventoryHex: string): string

Produces a JSON partial response for client-side navigation, including state, templates, and route chain.

CLI

The package also includes the webui CLI binary:

# Build templates to disk
npx webui build ./src --out ./dist

# Start a dev server
npx webui serve ./src --state ./data/state.json --port 3000

# Inspect a compiled protocol
npx webui inspect ./dist/protocol.bin

Platform support

| OS | Architecture | Package | |---|---|---| | Windows | x64 | @microsoft/webui-win32-x64 | | Windows | arm64 | @microsoft/webui-win32-arm64 | | macOS | arm64 | @microsoft/webui-darwin-arm64 | | macOS | x64 | @microsoft/webui-darwin-x64 | | Linux | x64 | @microsoft/webui-linux-x64 | | Linux | arm64 | @microsoft/webui-linux-arm64 |

Platform-specific packages are installed automatically as optional dependencies.

License

MIT