{"id":16012,"library":"electrobun","title":"Electrobun","description":"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.","status":"active","version":"1.16.0","language":"javascript","source_language":"en","source_url":"https://github.com/blackboardsh/electrobun","tags":["javascript","bun","desktop","app","cross-platform","typescript"],"install":[{"cmd":"npm install electrobun","lang":"bash","label":"npm"},{"cmd":"yarn add electrobun","lang":"bash","label":"yarn"},{"cmd":"pnpm add electrobun","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as the core runtime for Electrobun applications and development environment. It powers the main process and bundling.","package":"bun","optional":false},{"reason":"Electrobun is a TypeScript-first framework, and TypeScript is a peer dependency for project development.","package":"typescript","optional":false}],"imports":[{"note":"Main process APIs like BrowserWindow are imported from the 'electrobun/bun' subpath. Direct import from 'electrobun' will not provide these symbols.","wrong":"import { BrowserWindow } from 'electrobun';","symbol":"BrowserWindow","correct":"import { BrowserWindow } from 'electrobun/bun';"},{"note":"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.","wrong":"import { app } from 'electrobun/electron-bridge';","symbol":"app","correct":"import { app } from 'electrobun/bun';"},{"note":"Renderer process (webview) APIs for Inter-Process Communication (IPC) are imported specifically from the 'electrobun/view' subpath. This ensures context isolation.","wrong":"import { ipcRenderer } from 'electrobun';","symbol":"ipcRenderer","correct":"import { ipcRenderer } from 'electrobun/view';"},{"note":"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.","wrong":"const Electrobun = require('electrobun/bun');","symbol":"Electrobun (default import)","correct":"import Electrobun from 'electrobun/bun';"}],"quickstart":{"code":"bunx electrobun init my-electrobun-app\ncd my-electrobun-app\nbun install\n\n// src/main.ts (main Bun process)\nimport { BrowserWindow, app } from 'electrobun/bun';\nimport { join } from 'path';\n\napp.on('ready', () => {\n  const mainWindow = new BrowserWindow({\n    width: 800,\n    height: 600,\n    webPreferences: {\n      preload: join(app.getAppPath(), 'renderer', 'preload.ts'),\n      // sandbox: true, // Enable for untrusted content\n    },\n    title: 'Hello Electrobun App',\n    url: 'views://main/index.html' // or a remote URL like 'https://electrobun.dev'\n  });\n\n  // For development, open DevTools.\n  // mainWindow.webContents.openDevTools();\n});\n\napp.on('window-all-closed', () => {\n  if (process.platform !== 'darwin') {\n    app.quit();\n  }\n});\n\n// src/renderer/preload.ts (preload script for webview context)\nimport { ipcRenderer } from 'electrobun/view';\n\n// Expose ipcRenderer functions to the window object for the renderer process\nwindow.electrobun = {\n  sendMessage: (channel: string, data: any) => ipcRenderer.send(channel, data),\n  onMessage: (channel: string, callback: (...args: any[]) => void) => ipcRenderer.on(channel, callback),\n  invoke: (channel: string, ...args: any[]) => ipcRenderer.invoke(channel, ...args)\n};\n\n// Extend Window interface globally for TypeScript to recognize window.electrobun\ndeclare global {\n  interface Window {\n    electrobun: {\n      sendMessage: (channel: string, data: any) => void;\n      onMessage: (channel: string, callback: (...args: any[]) => void) => void;\n      invoke: (channel: string, ...args: any[]) => Promise<any>;\n    };\n  }\n}\n\n// package.json (add scripts)\n//  ...\n//  \"scripts\": {\n//    \"dev\": \"electrobun dev\",\n//    \"start\": \"bun run dev\",\n//    \"build\": \"electrobun build\"\n//  },\n//  ...\n\nbun run dev","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Electrobun 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.","severity":"breaking","affected_versions":">=1.0.0-beta.0"},{"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.","message":"Electrobun 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Electrobun 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Electrobun'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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The Bun runtime is not installed globally or is not accessible in the system's PATH. Electrobun heavily relies on Bun.","error":"error: bun: command not found"},{"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`).","cause":"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.","error":"Cannot find module 'electrobun/bun' or 'electrobun/view' from '...' at '...' error: module not found"},{"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).","cause":"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`.","error":"electrobun: command not found"}],"ecosystem":"npm"}