feat: add programmatic API surface and npm package distribution#83
Merged
Merged
Conversation
Create a unified public API for WebUI across Rust (crates.io) and
JavaScript (npm) consumers, following the esbuild single-package model.
Rust library crate (crates/webui/):
- Extract build logic from webui-cli into reusable library
- Public API: build(), build_to_disk(), inspect(), inspect_bytes()
- BuildOptions with CssStrategy (Link | Style), plugin, components
- BuildResult with BuildStats (duration, fragments, components, CSS,
protocol size, token count)
- WebUIError via thiserror with actionable error variants
- Re-exports WebUIHandler, ResponseWriter, WebUIProtocol, CssStrategy
- CssStrategy gains cli feature flag for clap::ValueEnum derive
- 29 unit tests including security (path traversal prevention)
CLI refactor (crates/webui-cli/):
- Depends on webui library instead of individual crates
- Renamed start command to serve (webui serve)
- CssMode/CssStrategy consolidated to single CssStrategy enum
- CLI is now a thin wrapper: args, terminal output, dev server
- Zero duplication with the library
Node.js bindings (crates/webui-node/):
- New napi exports: build(options), inspect(protocolData)
- JsBuildOptions, JsBuildResult, JsBuildStats napi object types
- 18 tests covering render + build + inspect
npm package (packages/webui/ -> @microsoft/webui):
- Single package: bin (CLI) + programmatic API (ESM TypeScript)
- Platform detection with workspace fallback for local dev
- Native addon loading via process.dlopen for .dylib/.so/.dll
- WASM fallback path with one-time warning
- workspace:* optional deps for local pnpm linking
- esbuild for JS compilation, tsc --emitDeclarationOnly for .d.ts
- 10 integration tests via node:test runner
Platform packages (packages/webui-{os}-{arch}/):
- 6 packages for darwin/linux/win32 x x64/arm64
- Each will contain CLI binary + .node native addon at publish time
Release infrastructure:
- .github/workflows/release.yml (disabled by default, workflow_dispatch)
- 6-target matrix build: CLI + node addon + WASM
- pnpm publish for workspace:* resolution at publish time
- GitHub Release with SHA256SUMS
- xtask version command for atomic version bumps across all
Cargo.toml and package.json files (skips node_modules)
CSS naming cleanup:
- CssMode removed, CssStrategy is the single source of truth
- Variants renamed: External -> Link, Inline -> Style
- Field renamed: css_mode -> css everywhere
- Updated across all crates, docs, and TypeScript types
Documentation updates:
- installation.md: npm as primary, cargo install, Cargo.toml
- cli/index.md: CSS modes link/style, webui serve, sidebar links
- handlers/node.md: @microsoft/webui API with Node/Bun/Deno tabs
- handlers/rust.md: webui crate with Actix Web/Axum/Hyper tabs
- New hydration.md: islands architecture, FAST custom elements,
@attr, @observable, events, f-ref, prepare() lifecycle
- plugins/index.md: tabbed Rust/Node/FFI handler examples
- README.md: simplified dev-focused with xtask command table
5da6c21 to
c7b3fd9
Compare
janechu
approved these changes
Mar 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Create a unified public API for WebUI across Rust (crates.io) and JavaScript (npm) consumers, following the esbuild single-package model.
Rust library crate (crates/webui/):
CLI refactor (crates/webui-cli/):
Node.js bindings (crates/webui-node/):
npm package (packages/webui/ -> @microsoft/webui):
Platform packages (packages/webui-{os}-{arch}/):
Release infrastructure:
CSS naming cleanup:
Documentation updates: