Electrobun

Common errors

• error: bun: command not found

  cause 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

  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.
  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

  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`.
  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).

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install electrobun npm
• yarn add electrobun yarn
• pnpm add electrobun pnpm

Imports

• BrowserWindow
  wrong:

  import { BrowserWindow } from 'electrobun';

  correct:

  import { BrowserWindow } from 'electrobun/bun';

  Main process APIs like BrowserWindow are imported from the 'electrobun/bun' subpath. Direct import from 'electrobun' will not provide these symbols.
• app
  wrong:

  import { app } from 'electrobun/electron-bridge';

  correct:

  import { app } from 'electrobun/bun';

  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
  wrong:

  import { ipcRenderer } from 'electrobun';

  correct:

  import { ipcRenderer } from 'electrobun/view';

  Renderer process (webview) APIs for Inter-Process Communication (IPC) are imported specifically from the 'electrobun/view' subpath. This ensures context isolation.
• Electrobun (default import)
  wrong:

  const Electrobun = require('electrobun/bun');

  correct:

  import Electrobun from '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.

Quickstart

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