Registry / web-framework / electrobun

electrobun

JSON →
library1.16.0jsnpmunverified

Electrobun is a framework designed for building ultra-fast, tiny, and cross-platform desktop applications using TypeScript. Leveraging the Bun runtime for the main process and native system WebViews (WebKit on macOS, WebView2 on Windows, WebKitGTK on Linux) for rendering, it offers a compelling alternative to Electron by drastically reducing bundle sizes (often around 12-64MB) and memory footprint, as it avoids bundling a full Chromium instance. The framework provides a complete TypeScript-first API for both main and renderer processes, including type-safe RPC for inter-process communication, and eliminates the need for languages like Rust (as seen in Tauri). It boasts a differential update mechanism (bsdiff) allowing for extremely small application updates, sometimes as low as 4KB. Current stable versions are `v1.x`, with active beta development continuing in the `v1.17.x-beta` series, indicating a frequent release cadence for enhancements and fixes.

npm install electrobun
INSTALL
IMPORT
SIG · ELECTROBUN
E
electrobun
web-frameworkjavascriptv1.16.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

BrowserWindow
✓ import { BrowserWindow } from 'electrobun/bun';
✗ import { BrowserWindow } from 'electrobun';
Main process APIs like BrowserWindow are imported from the 'electrobun/bun' subpath. Direct import from 'electrobun' will not provide these symbols.
app
✓ import { app } from 'electrobun/bun';
✗ import { app } from 'electrobun/electron-bridge';
The application lifecycle and core app events are accessed via the 'app' object from 'electrobun/bun'. While older examples might show '@electrobun/electron-bridge', 'electrobun/bun' is the current canonical path.
ipcRenderer
✓ import { ipcRenderer } from 'electrobun/view';
✗ import { ipcRenderer } from 'electrobun';
Renderer process (webview) APIs for Inter-Process Communication (IPC) are imported specifically from the 'electrobun/view' subpath. This ensures context isolation.
Electrobun (default import)
✓ import Electrobun from 'electrobun/bun';
✗ const Electrobun = require('electrobun/bun');
For convenience, main process APIs can also be accessed via a default import of the 'electrobun/bun' module, which exports an object containing all main process functionalities. Prefer named imports for better tree-shaking and clarity.

This quickstart initializes a new Electrobun project, demonstrates basic main process window creation, a preload script for exposing IPC to the renderer, and shows how to run the application in development mode.

bunx electrobun init my-electrobun-app cd my-electrobun-app bun install // src/main.ts (main Bun process) import { BrowserWindow, app } from 'electrobun/bun'; import { join } from 'path'; app.on('ready', () => { const mainWindow = new BrowserWindow({ width: 800, height: 600, webPreferences: { preload: join(app.getAppPath(), 'renderer', 'preload.ts'), // sandbox: true, // Enable for untrusted content }, title: 'Hello Electrobun App', url: 'views://main/index.html' // or a remote URL like 'https://electrobun.dev' }); // For development, open DevTools. // mainWindow.webContents.openDevTools(); }); app.on('window-all-closed', () => { if (process.platform !== 'darwin') { app.quit(); } }); // src/renderer/preload.ts (preload script for webview context) import { ipcRenderer } from 'electrobun/view'; // Expose ipcRenderer functions to the window object for the renderer process window.electrobun = { sendMessage: (channel: string, data: any) => ipcRenderer.send(channel, data), onMessage: (channel: string, callback: (...args: any[]) => void) => ipcRenderer.on(channel, callback), invoke: (channel: string, ...args: any[]) => ipcRenderer.invoke(channel, ...args) }; // Extend Window interface globally for TypeScript to recognize window.electrobun declare global { interface Window { electrobun: { sendMessage: (channel: string, data: any) => void; onMessage: (channel: string, callback: (...args: any[]) => void) => void; invoke: (channel: string, ...args: any[]) => Promise<any>; }; } } // package.json (add scripts) // ... // "scripts": { // "dev": "electrobun dev", // "start": "bun run dev", // "build": "electrobun build" // }, // ... bun run dev
Debug
Known issues
breakingElectrobun is under active and rapid development, evidenced by frequent beta releases (e.g., `v1.17.3-beta.X`). While `v1` has launched as stable, minor versions within `v1.x` and beta versions are subject to API changes and potential breaking shifts. Developers should monitor release notes closely.
fix
Review release notes for each update, especially when migrating between minor versions or beta cycles. Ensure your Bun runtime version is compatible with the Electrobun version.
affects: >=1.0.0-beta.0
gotchaElectrobun leverages native system WebViews (WebKit on macOS, WebView2 on Windows, WebKitGTK on Linux) for rendering. This provides smaller bundle sizes but means UI rendering behavior can exhibit subtle differences across operating systems. Cross-platform testing is crucial for UI consistency.
fix
Thoroughly test your application's UI on all target platforms (macOS, Windows, Linux) to ensure consistent appearance and behavior. Be mindful of platform-specific CSS or JavaScript quirks. Consider using 'bundleCEF' flag for Chromium consistency if needed, though this increases app size.
affects: >=1.0.0
gotchaElectrobun deeply relies on the Bun JavaScript runtime, which itself is rapidly evolving. While Bun offers significant performance benefits, its ecosystem is younger than Node.js, and stability for certain edge cases or platform interactions may still require long-term validation.
fix
Stay updated with Bun's releases and documentation. Report any Bun-related issues encountered within Electrobun to both project maintainers. Ensure your development environment has a consistent and recommended Bun version.
affects: >=1.0.0
gotchaElectrobun's API is split into specific subpaths: `electrobun/bun` for the main process (Bun runtime) and `electrobun/view` for the renderer process (webview context). Attempting to import APIs directly from the top-level `electrobun` package or using incorrect subpaths will result in module not found errors or undefined symbols.
fix
Always use the correct import paths: `import { ... } from 'electrobun/bun';` for main process code and `import { ... } from 'electrobun/view';` for renderer process (webview) code. Consult the official documentation for specific API import locations.
affects: >=1.0.0
Errors
Common errors & fixes
error: bun: command not found
The Bun runtime is not installed globally or is not accessible in the system's PATH. Electrobun heavily relies on Bun.
fix
Install Bun according to its official documentation (`curl -fsSL https://bun.sh/install | bash`) or ensure the `bun` executable is in your system's PATH.
Cannot find module 'electrobun/bun' or 'electrobun/view' from '...' at '...' error: module not found
The application code is attempting to import Electrobun APIs from an incorrect or non-existent path. Electrobun APIs are exposed via specific subpaths for main and renderer processes.
fix
Ensure main process code imports from `electrobun/bun` (e.g., `import { BrowserWindow } from 'electrobun/bun';`) and renderer process code imports from `electrobun/view` (e.g., `import { ipcRenderer } from 'electrobun/view';`). Verify that `electrobun` is correctly installed in `node_modules` (or `bun_modules`).
electrobun: command not found
The `electrobun` CLI executable is not found in the system's PATH. This can happen if it's installed locally but not invoked via `bunx` or `npx`.
fix
When using `electrobun` CLI commands (like `electrobun init`, `electrobun dev`, `electrobun build`), prefix them with `bunx` (e.g., `bunx electrobun init`) if `electrobun` is only a local dependency. Alternatively, ensure the `node_modules/.bin` directory is in your PATH, or install `electrobun` globally if preferred (though `bunx` is generally recommended for local CLI tools).
Upgrade
Version history
1.16.0latest on npm
Audit
Dependencies
bunrequiredRequired as the core runtime for Electrobun applications and development environment. It powers the main process and bundling.
typescriptrequiredElectrobun is a TypeScript-first framework, and TypeScript is a peer dependency for project development.
Agent activity
8 hits · last 30 days
node
8
Resources
electrobun — npm install electrobun · libregistry