Installation #

WebUI Framework can be installed and used with various environments and languages. This guide covers the most common installation methods.

There are two ways to install the WebUI build toolchain: as an npm package for JavaScript and TypeScript projects, or as a Rust crate for Rust projects. Both ship the same compiler and produce the same protocol output. Pick whichever fits your stack.

npm #

The @microsoft/webui npm package gives you:

• npx webui build - the CLI for building templates into protocols
• import { build, Protocol } from '@microsoft/webui' - a programmatic API for Node.js
• Native performance via platform-specific binaries (no compilation required)

npm install @microsoft/webui

yarn add @microsoft/webui

pnpm add @microsoft/webui

Configure package.json #

A typical project setup:

{
  "scripts": {
    "build": "webui build ./src --out ./dist --plugin=webui",
    "dev": "webui serve ./src --state ./data/state.json --plugin=webui --watch"
  },
  "dependencies": {
    "@microsoft/webui": "latest",
    "@microsoft/webui-framework": "latest"
  }
}

Run the development server with npm run dev and build for production with npm run build.

Cross-Platform Support #

The npm package uses platform-specific optional dependencies to deliver native binaries. Supported platforms are installed automatically - no Rust toolchain required.

Rust #

Rust users can install the CLI directly from crates.io:

cargo install microsoft-webui-cli

Then build your app:

webui build ./my-app --out ./dist

See the CLI Reference for full usage details.

.NET #

The managed .NET binding is packaged as Microsoft.WebUI:

dotnet add package Microsoft.WebUI

It targets .NET 8 and .NET 9. The package restores platform-specific Microsoft.WebUI.Runtime.* packages transitively, and .NET selects the matching native asset. Release builds stage .nupkg and .snupkg artifacts with Source Link and repository metadata; nuget.org publishing is manual until ESRP automation supports this project.

Prepare protocol.bin once for repeated rendering:

using Microsoft.WebUI;

using var protocol = new Protocol(
    File.ReadAllBytes("dist/protocol.bin"));
using var handler = new WebUIHandler("webui");

string html = handler.Render(
    protocol,
    """{"title":"Home"}""",
    "index.html",
    "/");

Protocol is thread-safe and owns the decoded protocol plus reusable indices. Keep it alive for the server lifetime and dispose it during shutdown.

The packages below are client-side runtime libraries. They are installed from npm regardless of whether your build toolchain is npm or Rust, since they ship as JavaScript that runs in the browser.

WebUI Framework (Client-Side Interactivity) #

For interactive Web Components with Islands Architecture, install the framework runtime:

npm install @microsoft/webui-framework

yarn add @microsoft/webui-framework

pnpm add @microsoft/webui-framework

This gives you:

• WebUIElement base class for interactive Web Components
• @attr and @observable decorators for reactive state
• Automatic SSR hydration with zero manual DOM reading
• Path-indexed targeted updates for minimal DOM mutations

Client-Side Router (Optional) #

For single-page navigation with client-side route transitions, install the router package:

npm install @microsoft/webui-router

yarn add @microsoft/webui-router

pnpm add @microsoft/webui-router

The router works with both WebUI Framework (@microsoft/webui-framework) and @microsoft/fast-element 3.x components. It's a separate package because it's only needed for apps with client-side navigation.

See the Routing guide for setup and usage.