Development tooling
Use Bun 1.4.4, pinned in .bun-version and package.json, with the committed
bun.lock. Run bun install --frozen-lockfile; CI uses the same pin and frozen
install. Node 26.13+ remains available for third-party CLI programs (CI uses 26.13.0),
including Storybook. The CSS and optional browser behaviors require no runtime
package dependencies.
bun lint
bun check
bun run check-boundaries
bun run test-boundaries
bun run test-dialog
bun run check-types
bun run test-behaviors
bun run build-site
bun run check-docs
bun run check-generated
bun pm pack --dry-run
The existing tests still import node:test. Bun's compatibility is partial;
this repository checks the exact discovered tests rather than assuming that all
Node runner features are supported. Keep explicit file selection in package
scripts when adding tests. See Bun's Node compatibility documentation.
The lockfile migration preserves resolved dependency versions and integrity
hashes for all 242 application dependencies; the 15 obsolete pnpm runtime/platform
packages are omitted. Only esbuild retains lifecycle-script trust, matching the previous
configuration. The existing Vite release-age exception remains in bunfig.toml; obsolete Biome exceptions are removed. No new exceptions are introduced. Do not broaden dependency trust
to repair a failing install.
Generated CSS, icons and declarations remain byte-identical across the migration. The existing declaration provenance header is deliberately retained to avoid changing public artifacts solely for tooling. Declarations must still be regenerated from source, not edited by hand.
Measurement limits
On one Linux x86-64 development environment, four serial process runs compared Node 24.19.0 with Bun 1.4.4. The median of the final three runs changed from 2.14s to 1.39s for the complete declaration/CSS build, and from 0.57s to 0.26s for all 41 tests. Test names and generated output hashes matched exactly.
These measurements cover development tooling, not browser rendering or game performance. The first process run was recorded separately; operating-system caches were not flushed, and no cold-network installation speed is claimed. Re-measure on the same machine and source revision before generalizing the result.
Native checks and formatting
Bun 1.4.4 is the current stable pin. bun lint is a project script combining
module-boundary validation with native bun fmt --check; Bun has no built-in
general-purpose lint command. bun check invokes the project check script,
including declaration verification and native type checks for the behavior and
consumer projects. Internal type-check commands use --no-script to avoid
recursing into the project script.
bun fmt replaces Biome for authored source and emitted declaration formatting.
TypeScript remains a development dependency because declaration emission is
still performed by its compiler; Bun's native checker does not emit declarations.
The package has no runtime dependencies. Generated CSS, icons and declarations
are checked separately rather than reformatted in place. This formatter change
is a one-time formatting migration, not a change to public behavior contracts.
Build ownership and cleanup
bun run build coordinates four generators: behavior declarations, React
declarations, runtime JavaScript and bundled CSS/icons. They run concurrently
because they own distinct files. The coordinator waits for all four and fails if
any fails;
site assembly and packaging only proceed after a successful build.
bun run check-generated uses that same coordinator before comparing with HEAD.
Runtime compilation finishes in memory before synchronizing .js files.
Declarations finish in a temporary directory before synchronizing .d.ts files.
The shared generated-file writer removes retired modules of the same file type,
including nested owners, and preserves other generators' files. Syntax/type
errors preserve the last successful outputs. Check mode reports stale and retired
declarations without mutation. This prevents an incremental build from packaging
removed vanilla behaviors or obsolete component groupings.
Both declaration builds compile into unique temporary directories with emission on errors disabled. The directory is removed on success or failure. The generator resolves tools and paths relative to the repository, so it can be invoked from another working directory.
Use bun run clean to remove .site, storybook-static and legacy .types
output, plus disposable dist/behaviors and dist/react. It preserves committed CSS, icons and installed dependencies.
Then bun run build-site recreates the package, Storybook and documentation site.
Storybook runs after package generation so it never reads icons while they are
being regenerated. No build-speed improvement is claimed without measurement.
Native build APIs
Generators and checks use Bun.file, Bun.write, Bun.Glob, native URL/path
conversion and checked Bun.spawnSync subprocesses. Generated CSS, declarations
and site contents must remain unchanged when changing these implementation APIs.
Failed compilers must not replace an existing declaration, and temporary source
copies must be removed on success or failure.
Directory copying, temporary-directory creation, recursive cleanup and path normalization still use Bun's Node-compatible standard-library APIs where there is no equivalent direct Bun file operation. These run inside Bun; they do not launch Node. Third-party tooling may still require Node. Browser modules continue to use browser APIs, not Bun globals.
All authored tooling now uses .ts and runs directly with Bun. bun run build
generates browser JavaScript and package declarations; see TypeScript
for source-archive and static-site build instructions.