Electrobun: a TypeScript desktop framework built around Hutch, Cottontail and byte-level diffs

What Electrobun is for, and who it is aimed at

Electrobun is a desktop application framework written in TypeScript. The README describes it as a "solution-in-a-box" for building, updating, and shipping fast, compact, cross-platform desktop apps. The intended user is a TypeScript developer who wants the main process and the webview code in one language, without hand-managing a native shell around a browser engine.

The project splits responsibilities across named components. Hutch is the native build and workspace CLI. Cottontail is the default JavaScript runtime, built on JSC rather than V8. The platform layer combines Zig, Objective-C, and C++. That split matters when you evaluate it: you are not adopting a single library, you are adopting a CLI, a runtime, and a native layer that are versioned together.

The stated goals are narrow and testable. Isolation between main and webview processes with typed RPC between them. Small self-extracting bundles when using the system webview. Small updates that use binary patches before falling back to a compressed full download. The README claims the workflow gets you writing code in five minutes and distributing in ten. Treat that as a marketing target, not a measurement; the repository does not publish a benchmark backing it.

How Hutch, Cottontail and the platform layer fit together

The mechanism is a release-resolution pipeline rather than a bundler plugin. When you run the initializer, Hutch resolves an Electrobun release, verifies the platform archive, and installs it under `~/.hutch/releases/electrobun`. It then copies that release's SDKs into the project's generated `.hutch/devkit` sysroot. So the SDK your project compiles against is a copy inside the project tree, sourced from a verified archive, not something resolved from `node_modules` at build time.

Version pinning has three modes. Published templates include the exact Electrobun release they were tested with. A hand-written project can omit the pin, in which case Hutch uses an npm-supplied paired default or floats on the active release channel. That is a real decision point: floating gets you fixes without editing config, and it also means a build can move under you.

Package management is deliberately separate from the runtime choice. Hutch has a built-in npm-compatible resolver, installs JavaScript dependencies by default, and writes `hutch.lock`. A project's `hutch.config.ts` can instead select npm, Bun, pnpm, Yarn, or a custom executable, and Hutch delegates package operations to that choice. The README states explicitly that package management is independent of whether the app's main process runs on Cottontail or Bun. Those are two orthogonal axes, which is unusual and worth knowing before you debug a dependency problem in the wrong layer.

Installing Electrobun and running a first project

The documented path is the install script, which puts Hutch on the machine, followed by the initializer, which creates the project. Initialization requires network access because it fetches the current template catalog and the selected template. Later builds can reuse exact releases and managed toolchains already installed.

curl -fsSL https://hutch.blackboard.sh/hutch/install.sh | sh
hutch electrobun init

Expect an interactive initializer. After it finishes you should have a project directory with a generated `.hutch/devkit` sysroot and an Electrobun release under `~/.hutch/releases/electrobun`.

If you would rather not run a shell script first, the README gives an npm and Bun bootstrap for the same initializer. The npm package is dependency-free, downloads the exact paired Hutch archive from that version's Electrobun GitHub Release when needed, verifies and caches it, and forwards the command. It also ensures a compatible global launcher for the generated project's `hutch` tasks. It does not carry or own the Electrobun runtime or SDKs.

npx electrobun init
# or
bunx electrobun init

Once dependencies are installed, `hutch pm exec` runs project-local package binaries, which is how you invoke tooling that belongs to the project rather than the global environment.

hutch pm exec

The README does not document a rollback command, so if a floated release breaks a build, the recovery path is to pin the release in the project rather than to undo the install.

Where the design costs you: beta releases and undocumented edges

The most concrete limitation is release maturity. The recent releases listed for the repository are v2.0.2-beta.27, v2.0.2-beta.26 and v2.0.2-beta.25, all published on 2026-09-13. There is no stable v2.0.2 in that list. If your team has a policy against shipping on beta dependencies, this framework fails that policy today, regardless of how the code behaves.

The second limitation is documentation surface. The README points to the framework site for API documentation and guides, and the repository has a `docs/` directory, but the README itself does not describe rollback, does not describe how to pin a release in a hand-written project beyond saying the pin is optional, and does not describe mobile targets. The related searches include Electrobun Android and Electrobun mobile; nothing in the repository confirms that either is supported, so treat a mobile requirement as a disqualifier until you find documentation that says otherwise.

The third is the install model itself. Requiring a global CLI plus a per-project sysroot copy is more moving parts than adding a dependency to `package.json`. It buys reproducibility and platform archives, and it costs you a network step on first init and a toolchain that lives outside your lockfile. Teams with strict artifact-provenance rules will want to check whether `~/.hutch/releases/electrobun` and `.hutch/devkit` fit their policy before they start.

Electrobun compared with Electron, and where the difference shows

Electron is the natural comparison, and it is the one people search for. The difference is not a feature list, it is what the app ships. Electron bundles Chromium and Node with every app, which gives you one rendering engine everywhere and a large download. Electrobun defaults to the system webview and offers a `bundleCEF` flag for teams that want Chromium bundled and pinned instead, described in the README as a tradeoff of consistency over file size. That flag is the honest summary of the whole comparison: you choose consistency or size, and the framework lets you choose per project.

The update mechanism differs in the same direction. Electrobun uses a Zig-optimized BSDIFF implementation that the README says can produce kilobyte-scale updates, with a fallback to a compressed full download. Bundles are self-extracting and use Zstandard compression. If your distribution problem is update bandwidth rather than initial download, this is the part of the project that matters most to you.

The runtime choice is the other axis. Cottontail is JSC-based and is the default, while the README notes that the main process can run on Bun instead. That is a meaningfully different proposition from Electron's single embedded runtime, and it is also why the package manager and runtime are configured independently.

Webviews, GPU surfaces, and the parts beyond a plain window

Electrobun exposes two custom HTML elements, `<electrobun-webview>` and `<electrobun-wgpu>`, which let you composite isolated webviews and native GPU surfaces into your UI. The `bundleWGPU` flag lets you go from Bun TypeScript to WGPU to control a native GPU surface without a webview at all. There are Three.js and Babylon.js adapters that the README says work directly in the Cottontail main process.

This is the part of the project that is hardest to evaluate from documentation alone, and it is where I would be most careful. Compositing isolated webviews and native GPU surfaces into one window is a rendering problem with platform-specific failure modes, and the README does not enumerate them. If your app is a form over a database, none of this matters and you are paying complexity for nothing. If your app draws a canvas or a 3D scene next to DOM content, it is the reason to look at Electrobun at all.

The `bundleWGPU` option also changes what your app depends on. A WGPU surface is not a webview, so the consistency argument that applies to `bundleCEF` does not transfer; you are now responsible for GPU driver behavior across the machines you ship to.

Licence, maintenance and what upgrades actually cost

The repository is MIT licensed, which permits commercial and closed-source use and requires preserving the copyright notice and licence text. That is the whole of the licence implication here; questions about your own distribution obligations belong with your legal team, not with this article.

Maintenance signals are current. The repository is not archived, and the last push was on 2026-09-17. The release cadence is fast: three beta releases on 2026-09-13 alone. Fast beta cadence cuts both ways. You get fixes quickly, and you also get a moving target, which is why the release pin in a template matters and why a hand-written project that floats on the active release channel should expect to re-verify builds more often.

Upgrade cost is concentrated in the native layer, not the TypeScript. A new Electrobun release means a new platform archive verified and installed under `~/.hutch/releases/electrobun` and new SDKs copied into `.hutch/devkit`. If you have pinned a release in your project, that is a deliberate step; if you have not, it happens on the channel's schedule. The README does not describe a rollback command, so budget for pinning before you upgrade rather than after.

Editorial conclusion

Adopt Electrobun if you already write TypeScript for the main process and webviews and you care about bundle size and small updates more than ecosystem age: `hutch electrobun init` gives you a working template, and the RPC layer between main and webview is part of the design rather than an add-on. Do not adopt it if you need a stable, non-beta release line, a fully documented API surface, or mobile targets, because the current releases are all v2.0.2-beta and the README does not describe Android or iOS support. Before committing, verify three things in your own project: that your target platform has a published Electrobun release archive under `~/.hutch/releases/electrobun`, that your chosen package manager is the one `hutch.config.ts` selects, and that your first build produces the self-extracting bundle you expect on the platform you ship to.

Frequently asked questions

Official sources

1. blackboardsh/electrobun on GitHub
2. License: MIT
3. Project website
4. README
5. Releases