Electrobun v2.x

Electrobun 2.0 introduces a new build tool and JavaScript runtime, six supported main-process runtimes, native builds across macOS, Windows, and Linux, and a large reconciliation of the 1.x issue and pull-request backlog.

By the numbers

Resolved 138 issues and 47 pull requests during the 2.0 reconciliation.
Tracks 8,460 owned Node and Bun compatibility test files across Cottontail and Hutch. The current manifests enable 8,436 files and record 24 explicit expected failures.
Backed by roughly 1,800 first-party tests and Kitchen Sink scenarios, in addition to the owned compatibility corpus.
Supports six main-process runtimes: Cottontail, Bun, Zig, Rust, Go, and Odin.

The original 2.0 size comparison used Cottontail 0.2.3 and Bun 1.3.13. Cottontail was smaller on every supported release target measured. These figures are extracted executable sizes, not compressed archive sizes.

Platform	Cottontail	Bun	Reduction
macOS ARM64	57,714,960 B	63,072,928 B	8.5%
Linux x64	59,480,576 B	101,814,712 B	41.6%
Linux ARM64	55,183,872 B	101,309,000 B	45.5%
Windows x64	55,587,328 B	117,660,760 B	52.8%

Hutch build tooling

Hutch replaces the old project-vendored Electrobun CLI for project scripts, devkit synchronization, builds, native toolchains, and distribution.
Hutch’s built-in npm-compatible resolver owns JavaScript dependencies and hutch.lock by default. npm, pnpm, Yarn, or Bun may be selected explicitly; Cargo and Go modules remain authoritative for their ecosystems.
electrobun.version is an optional exact override in hutch.config.ts. Otherwise npm-launched commands use the package’s paired release and direct Hutch projects float on the release channel, remaining steady between explicit syncs. Hutch verifies the resolved platform core archive in ~/.hutch, then copies its SDKs into the generated project .hutch/devkit sysroot for builds and editor tooling.
Production and canary Hutch installations can coexist globally. Projects can pin Hutch and Cottontail independently with a first-line pragma.
hutch electrobun init now opens an interactive, keyboard-navigable template chooser followed by an editable project-name prompt. Template catalogs ship per Electrobun channel and are downloaded on demand instead of increasing the Hutch executable size.
npx electrobun init and bunx electrobun init converge on that same initializer. One dependency-free npm bootstrap shares the Electrobun release version, downloads, verifies, and caches its paired Hutch archive from that GitHub Release when needed, and forwards all arguments. It carries no Electrobun core or SDK. Published templates pin the exact release they were tested with; framework contributors run repository templates against the freshly built local devkit.
Current Vite templates require Hutch 0.24 or later for catalog tool checks and built-in hutch pm exec. A global Hutch 0.23 installation cannot enforce that catalog declaration and must be advanced with its legacy hutch self update production command before initializing a current template; use hutch upgrade for later updates. The npm bootstrap supplies its paired Hutch automatically.

Cottontail runtime

Cottontail is the default TypeScript main-process runtime and provides broad Node.js and Bun compatibility for existing application code and packages.
electrobun/main is the canonical, runtime-neutral main-process SDK namespace. electrobun/bun remains available as a deprecated alias.
Bun remains an explicit main-process option for applications that need to retain the Bun runtime. Electrobun 2.0 pins Bun 1.4.0 for those applications; Hutch acquires and packages that exact runtime.

Native main processes

Applications can use Zig, Rust, Go, or Odin without shipping a JavaScript runtime. Hutch uses a compatible system compiler when available and otherwise acquires Electrobun’s pinned toolchain. The SDKs share the same core window, view, RPC, lifecycle, and WGPU contracts.

Odin is new in 2.0 and includes native WGPU templates for data-oriented particles, fluid simulation, soft-body bunny physics, a cellular alchemy sandbox, and procedural tree generation. Windows Odin builds are currently x64-only and require Visual Studio Build Tools; the pinned compiler is pre-1.0, and cross-compilation is not yet supported.

Electrobun UI (experimental)

Electrobun 2.0 ships an experimental reactive UI runtime at electrobun/main/ui: GPU-rendered application UI in plain TypeScript with no webview, browser DOM, or compile step.

Warren, an explicit fine-grained reactivity model: signal, store, live, memo, inert, cleanup, batch — reactivity exists only inside visible live()/memo() scopes — plus JSX with control-flow components (Show, For, Switch/Match) and no added build tooling (Cottontail’s built-in transpiler).
A DOM renderer, electrobun/browser/ui: the same Warren core and JSX rendered into real DOM inside webviews — any HTML/SVG tag, keyed For reconciliation over real nodes, Portal, explicit two-way inputs — so main-process GPU chrome and webview documents share one model (and shared store/model code runs unchanged on both sides).
A retained tree with flex-style layout, hit testing, and invalidation-only rendering — one instanced Dawn draw call per dirty frame, zero work while idle or hidden.
Elements: box/row/column, text, spacer, dynamic regions, keyed each lists, scroll containers, a controlled textInput, and native-layer elements that position real webviews and WGPU views from the same layout tree.
createUIWindow for full-window chrome (including transparent, always-on-top, draggable frameless panels), createUIView for rendering into any WGPU view, and a new <electrobun-ui> browser tag that layers main-process UI over web content via registerUIRoot.
Three new templates showcase it: ui-wgpu (reactive counter with embedded webview and Mandelbrot surface), ui-color-picker (tray eyedropper with a live pixel loupe), and ui-launcher (always-on-top command palette with fuzzy app search and an inline calculator).

See the Electrobun UI guide for a hello world and current limitations.

App and platform fixes

Highlights from the 2.0 reconciliation include:

Shared close cancellation, typed BrowserView creation events, JSON-array dialog results, unbounded user-controlled dialog timeouts, window visibility fixes, and consistent behavior across all six main-process SDKs.
System-webview console forwarding in development, CEF lifecycle and shutdown cleanup, persistent partition and OPFS corrections, draggable-region fixes, and broader WGPU adapter and surface coverage.
macOS fixes for docked DevTools layout and hover crashes, traffic-light positioning across resize, CEF sizing, code signing, and deployment targets.
Windows wide-character paths and UI text, including WebView2 and CEF data directories under non-ASCII user profiles; per-monitor DPI setup, correct initial content bounds, permission handling, native window behavior, icon embedding, and installer shutdown.
Linux WebKit and CEF lifecycle fixes, wheel scrolling, GTK grow and shrink behavior, native chooser integration, desktop-entry packaging, adjacent archive extraction, launch dependency diagnostics, ABI checks, and an initial Flatpak output path.
Isolated Kitchen Sink matrix builds, remote release templates, R2-hosted owned dependencies, and cross-platform stable/canary packaging.

Platforms and channels

The release pipeline builds application bundles and distributable artifacts on macOS ARM64, Windows x64, Linux x64, and Linux ARM64. Apps can use the system webview or CEF on each supported operating system.

Hutch’s Electrobun build environments are dev, canary, and stable. Canary and stable are independent release channels.

See Migrate from Electrobun 1.x for the required project changes.