Skip to content

feat: add programmatic API surface and npm package distribution#83

Merged
mohamedmansour merged 1 commit into
mainfrom
mmansour/api-surface-npm-distribution
Mar 7, 2026
Merged

feat: add programmatic API surface and npm package distribution#83
mohamedmansour merged 1 commit into
mainfrom
mmansour/api-surface-npm-distribution

Conversation

@mohamedmansour

@mohamedmansour mohamedmansour commented Mar 7, 2026

Copy link
Copy Markdown
Contributor

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:

  • 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

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
@mohamedmansour mohamedmansour force-pushed the mmansour/api-surface-npm-distribution branch from 5da6c21 to c7b3fd9 Compare March 7, 2026 08:29
@mohamedmansour mohamedmansour requested review from a team, akroshg and janechu March 7, 2026 08:31
@mohamedmansour mohamedmansour merged commit fc2af4d into main Mar 7, 2026
10 checks passed
@mohamedmansour mohamedmansour deleted the mmansour/api-surface-npm-distribution branch March 7, 2026 09:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants