Windows

Requirements

• Windows 10 version 1809 or newer
• Windows 11 recommended for the Segoe Fluent Icons font
• .NET 8 SDK or newer
• Node.js 22 or newer
• pnpm 11

The project targets net8.0-windows and Windows App SDK 1.8. CI uses the .NET 8 SDK.

pnpm install
dotnet build hosts/windows/NatuiHost -c Release -p:Platform=x64
pnpm demo

pnpm demo starts the React Fast Refresh development server. Use pnpm demo:start to open the example once without watching.

The host is an unpackaged, self-contained WinUI 3 executable. The JavaScript bridge locates normal debug and release output paths automatically. Set NATUI_HOST when your executable is elsewhere:

$env:NATUI_HOST = "C:\path\to\NatuiHost.exe"
pnpm demo

Do not use dotnet run as the spawn target. Its wrapper process breaks the parent-child lifetime and standard-stream semantics that NatUI expects.

Verification status

The base demo and its Node-mode end-to-end suite have passed against a real WinUI 3 window, including tree dumps, interaction events, controlled edits, and screenshots.

The Windows host also supports in-process V8 execution:

pnpm build
pnpm --filter natui-demo build:embedded
hosts\windows\NatuiHost\bin\x64\Release\net8.0-windows10.0.19041.0\win-x64\NatuiHost.exe --bundle examples\demo\dist\embedded.js

Run pnpm verify:embedded to exercise the embedded tree, interactions, sequence acknowledgements, screenshot path, and closed-input lifecycle.

Package a Windows application

From the repository root:

pnpm package:demo

The command reads examples/demo/natui.app.json and writes one portable, architecture-specific, self-contained EXE:

examples\demo\dist\package\NatUIDemo-<version>-windows-x64.exe

An ARM64 build uses the windows-arm64.exe suffix. The one EXE contains the application JavaScript, generated manifest, WinUI host, .NET runtime, Windows App SDK runtime, and V8 dependencies. It does not need Node or a machine-wide .NET installation at runtime.

When icons.windows is configured, packaging requires a valid multi-image .ico container and embeds it in the executable as the application icon.

At launch, the .NET single-file host extracts runtime dependencies to a cache under the current user's temporary directory. The cache is runtime-managed and is not a machine-wide installation.

Run the packaged lifecycle verification in a real desktop session:

pnpm verify:package

The check launches the EXE from an unrelated working directory, validates the protocol and host API handshake, waits for the native tree, requests a normal window close, and requires exit code 0.

Headless Windows CI also builds the EXE and inspects its PE header and .NET bundle table. It requires exactly one output file and checks that the embedded runtime includes WinUI, V8, ICU, resources.pri, and the application payload.

The reference packager does not sign the EXE or create an installer, automatic updater, single-instance coordinator, or multi-window application. See application bundles.

See platform support for component-level differences.