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 for downstream signing and publishing. NuGet.org publishing is not automatic until an approved Microsoft-certificate signing path is available for .nupkg packages.

See the .NET integration guide for buffered and progressive ASP.NET response examples.

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.

Python #

The microsoft-webui PyPI package is a native PyO3 binding, not a ctypes wrapper:

The microsoft-webui package is not published to PyPI yet. Wheels and a source distribution are built and attached to each GitHub Release; install one directly, or build from a checkout with maturin.

pip install ./microsoft_webui-<version>-cp311-abi3-<platform>.whl

It ships prebuilt wheels for CPython 3.11+ (Windows, macOS, and manylinux, on x86_64 and ARM64) plus one sdist, and is runtime-only — it renders compiled protocols but does not build them. Produce protocol.bin with webui build (the npm or Rust CLI above), then render it from Python:

from microsoft_webui import Renderer

renderer = Renderer.from_file("dist/protocol.bin", plugin="webui")

html = renderer.render({"title": "Home"}, request_path="/")  # -> bytes

Renderer decodes and indexes the protocol once, is thread-safe, and releases the GIL for the duration of each render. See Python for WSGI, ASGI, and progressive-streaming examples.

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.

AI Coding Agents #

WebUI ships its framework reference inside @microsoft/webui as ai.md. The small webui-reference agent skill tells GitHub Copilot, Claude Code, Cursor, Codex, and other supported agents to read that installed reference before working on WebUI code.

Install the loader once, after adding @microsoft/webui to your project:

npx skills add microsoft/webui --skill webui-reference

yarn dlx skills add microsoft/webui --skill webui-reference

pnpm dlx skills add microsoft/webui --skill webui-reference

The skill lands in .agents/skills/webui-reference/, which GitHub Copilot reads directly. The installer also sets it up in agent-specific skill directories where needed.

The loader asks the agent to read node_modules/@microsoft/webui/ai.md from the application's installed dependencies. Upgrading @microsoft/webui updates the guidance with it. You do not need to rerun skills add for reference updates. If you upgrade during an agent session, ask the agent to reread the installed reference.

If you previously installed the full reference as a skill, run the install command above once more in the same scope (project or -g) to replace it with the loader. Commit a project-local installation to share it with your team.

Useful flags:

To try the reference in a single session without installing it:

npx skills use microsoft/webui@webui-reference | copilot

This also uses the reference from your installed package. Releases predating bundled ai.md, and Rust-only toolchains without @microsoft/webui, need a reference from their matching release instead. The loader reports missing guidance rather than silently using a newer version.