electrobun-best-practices

Electrobun Best Practices

Electrobun builds cross-platform desktop apps with TypeScript and Bun. This skill gives safe defaults, typed RPC patterns, and operational guidance for build/update/distribution.

Docs: https://blackboard.sh/electrobun/docs/

Pair with TypeScript Best Practices

Always load typescript-best-practices alongside this skill.

Version and Freshness

Electrobun APIs evolve quickly. Before relying on advanced options or platform-specific behavior, verify against current docs and CLI output.

Architecture

Electrobun apps run as Bun apps:

• Bun process (main): imports from electrobun/bun
• Browser context (views): imports from electrobun/view
• Shared types: RPC schemas shared between both contexts

IPC between bun and browser contexts uses postMessage, FFI, and (in some paths) encrypted WebSockets.

Quick Start

bunx electrobun init
bun install
bun start

Recommended scripts:

{
  "scripts": {
    "start": "electrobun run",
    "dev": "electrobun dev",
    "dev:watch": "electrobun dev --watch",
    "build:dev": "bun install && electrobun build",
    "build:canary": "electrobun build --env=canary",
    "build:stable": "electrobun build --env=stable"
  }
}

Secure Defaults

Use this baseline for untrusted or third-party content:

import { BrowserWindow } from "electrobun/bun";

const win = new BrowserWindow({
  title: "External Content",
  url: "https://example.com",
  sandbox: true,                  // disables RPC, events still work
  partition: "persist:external",
});

win.webview.setNavigationRules([
  "^*",                          // block everything by default
  "*://example.com/*",           // allow only trusted domain(s)
  "^http://*",                   // enforce HTTPS
]);

win.webview.on("will-navigate", (e) => {
  console.log("nav", e.data.url, "allowed", e.data.allowed);
});

Security checklist:

• Use sandbox: true for untrusted content.
• Apply strict navigation allowlists.
• Use separate partition values for isolation.
• Validate all host-message payloads from <electrobun-webview> preload scripts.
• Do not write to PATHS.RESOURCES_FOLDER at runtime; use Utils.paths.userData.

Typed RPC (Minimal Pattern)

// src/shared/types.ts
import type { RPCSchema } from "electrobun/bun";

export type MyRPC = {
  bun: RPCSchema<{
    requests: {
      getUser: { params: { id: string }; response: { name: string } };
    };
    messages: {
      logToBun: { msg: string };
    };
  }>;
  webview: RPCSchema<{
    requests: {
      updateUI: { params: { html: string }; response: boolean };
    };
    messages: {
      notify: { text: string };
    };
  }>;
};

// bun side
import { BrowserView, BrowserWindow } from "electrobun/bun";
import type { MyRPC } from "../shared/types";

const rpc = BrowserView.defineRPC<MyRPC>({
  handlers: {
    requests: {
      getUser: ({ id }) => ({ name: `user-${id}` }),
    },
    messages: {
      logToBun: ({ msg }) => console.log(msg),
    },
  },
});

const win = new BrowserWindow({
  title: "App",
  url: "views://mainview/index.html",
  rpc,
});

await win.webview.rpc.updateUI({ html: "<p>Hello</p>" });

// browser side
import { Electroview } from "electrobun/view";
import type { MyRPC } from "../shared/types";

const rpc = Electroview.defineRPC<MyRPC>({
  handlers: {
    requests: {
      updateUI: ({ html }) => {
        document.body.innerHTML = html;
        return true;
      },
    },
    messages: {
      notify: ({ text }) => console.log(text),
    },
  },
});

const electroview = new Electroview({ rpc });
await electroview.rpc.request.getUser({ id: "1" });
electroview.rpc.send.logToBun({ msg: "hello" });

Events and Shutdown

Use before-quit for shutdown cleanup instead of relying on process.on("exit") for async work.

import Electrobun from "electrobun/bun";

Electrobun.events.on("before-quit", async (e) => {
  await saveState();
  // e.response = { allow: false }; // optional: cancel quit
});

Important caveat:

• Linux currently has a caveat where some system-initiated quit paths (for example Ctrl+C/window-manager/taskbar quit) may not fire before-quit. Programmatic quit via Utils.quit()/process.exit() is reliable.

Common Patterns

• Keyboard shortcuts (copy/paste/undo): define an Edit ApplicationMenu with role-based items.
• Tray-only app: set runtime.exitOnLastWindowClosed: false, then drive UX from Tray.
• Multi-account isolation: use separate partition values per account.
• Chromium consistency: set bundleCEF: true and defaultRenderer: "cef" in platform config.

Troubleshooting

• RPC calls fail unexpectedly:
  • Check whether the target webview is sandboxed (sandbox: true disables RPC).
  • Confirm shared RPC types match both bun and browser handlers.
• Navigation blocks legitimate URLs:
  • Review setNavigationRules ordering; last match wins.
  • Keep ^* first only when you intentionally run strict allowlist mode.
• Updater says no update:
  • Verify release.baseUrl and uploaded artifacts/ naming ({channel}-{os}-{arch}-...).
  • Confirm channel/build env alignment (canary vs stable).
• User sessions leak across accounts:
  • Use explicit per-account partitions and manage cookies via Session.fromPartition(...).
• Build hooks not running:
  • Ensure hook paths are correct and executable via Bun.
  • Inspect hook env vars (for example ELECTROBUN_BUILD_ENV, ELECTROBUN_OS, ELECTROBUN_ARCH).

Reference Files

• Build config, artifacts, and hooks: reference/build-config.md
• BrowserWindow, BrowserView, and webview tag APIs: reference/window-and-webview.md
• Menus, tray, events, updater, utils/session APIs: reference/platform-apis.md