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

Build Config Reference

Contents

• electrobun.config.ts baseline
• Build fields and runtime fields
• views:// bundled assets
• Distribution artifact model
• Build lifecycle hooks

electrobun.config.ts Baseline

import type { ElectrobunConfig } from "electrobun";

export default {
  app: {
    name: "My App",
    identifier: "com.example.myapp",
    version: "1.0.0",
    urlSchemes: ["myapp"], // macOS deep-linking support
  },
  runtime: {
    exitOnLastWindowClosed: true,
    // custom keys are readable at runtime via BuildConfig.get()
  },
  build: {
    bun: {
      entrypoint: "src/bun/index.ts",
      // Bun.build pass-through options supported (plugins/external/sourcemap/minify/etc.)
    },
    views: {
      mainview: {
        entrypoint: "src/mainview/index.ts",
      },
    },
    copy: {
      "src/mainview/index.html": "views/mainview/index.html",
      "src/mainview/style.css": "views/mainview/style.css",
    },
    useAsar: false,
    asarUnpack: ["*.node", "*.dll", "*.dylib", "*.so"],
    // watch: ["scripts"],
    // watchIgnore: ["**/*.generated.*"],
    mac: {
      codesign: true,
      notarize: true,
      bundleCEF: false,
      defaultRenderer: "native", // or "cef" when bundleCEF is true
      entitlements: {},
      icons: "icon.iconset",
    },
  },
  scripts: {
    preBuild: "./scripts/pre-build.ts",
    postBuild: "./scripts/post-build.ts",
    postWrap: "./scripts/post-wrap.ts",
    postPackage: "./scripts/post-package.ts",
  },
  release: {
    baseUrl: "https://storage.example.com/myapp/",
  },
} satisfies ElectrobunConfig;

Runtime Access

import { BuildConfig } from "electrobun/bun";

const cfg = await BuildConfig.get();
console.log(cfg.runtime?.exitOnLastWindowClosed);

Bundled Assets (views://)

views:// maps to bundled static assets and works in BrowserWindow/BrowserView URLs plus HTML and CSS references.

<script src="views://mainview/index.js"></script>
<link rel="stylesheet" href="views://mainview/style.css" />
<img src="views://assets/logo.png" />

Distribution Artifacts

Non-dev builds (canary/stable) produce flat artifacts prefixed:

• {channel}-{os}-{arch}-update.json
• platform installers
• .tar.zst update bundle
• .patch incremental patch (typically from previous version)

General guidance:

• Upload entire artifacts/ output to static hosting.
• Keep historical patch files if you want chain-style incremental updates available to clients.
• If patch trail is unavailable, updater falls back to full bundle download.

Build Lifecycle Hooks

Execution order:

• preBuild
• postBuild
• postWrap
• postPackage

Common env vars:

• ELECTROBUN_BUILD_ENV
• ELECTROBUN_OS
• ELECTROBUN_ARCH
• ELECTROBUN_BUILD_DIR
• ELECTROBUN_APP_NAME
• ELECTROBUN_APP_VERSION
• ELECTROBUN_APP_IDENTIFIER
• ELECTROBUN_ARTIFACT_DIR
• ELECTROBUN_WRAPPER_BUNDLE_PATH (postWrap only)

Platform APIs

Contents

• Application and context menus
• System tray
• Global events and shutdown lifecycle
• Updater
• Utils
• GlobalShortcut, Screen, Session

Application Menu

import Electrobun, { ApplicationMenu } from "electrobun/bun";

ApplicationMenu.setApplicationMenu([
  { submenu: [{ label: "Quit", role: "quit" }] },
  {
    label: "Edit",
    submenu: [
      { role: "undo" },
      { role: "redo" },
      { type: "separator" },
      { role: "cut" },
      { role: "copy" },
      { role: "paste" },
      { role: "pasteAndMatchStyle" },
      { role: "delete" },
      { role: "selectAll" },
      { type: "separator" },
      { label: "Save", action: "save", accelerator: "s" },
    ],
  },
]);

Electrobun.events.on("application-menu-clicked", (e) => {
  console.log("action", e.data.action);
});

Use role-based items to enable native shortcuts (quit, copy, paste, etc.).

Context Menu

import Electrobun, { ContextMenu } from "electrobun/bun";

ContextMenu.showContextMenu([
  { label: "Copy", role: "copy" },
  { label: "Paste", role: "paste" },
  { type: "separator" },
  { label: "Custom", action: "custom", accelerator: "s" },
]);

Electrobun.events.on("context-menu-clicked", (e) => {
  console.log("context action", e.data.action);
});

System Tray

import { Tray } from "electrobun/bun";

const tray = new Tray({
  title: "My App",
  image: "views://assets/icon-32-template.png",
  template: true,
  width: 32,
  height: 32,
});

tray.on("tray-clicked", () => {
  tray.setMenu([
    { label: "Show Window", action: "show" },
    { type: "separator" },
    { label: "Quit", role: "quit" },
  ]);
});

Related events:

• tray-clicked
• tray-item-clicked

Events and Shutdown Lifecycle

import Electrobun from "electrobun/bun";

Electrobun.events.on("will-navigate", (e) => {
  e.response = { allow: true };
});

Electrobun.events.on("open-url", (e) => {
  console.log("deep link", e.data.url);
});

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

Quit path guidance:

• Use before-quit for cleanup and optional quit cancellation.
• process.on("exit") is sync-only and should be last-resort.
• Linux caveat: some system-initiated quit paths may not currently fire before-quit; programmatic quit (Utils.quit / process.exit) is reliable.

Updater

import { Updater } from "electrobun/bun";

const local = await Updater.getLocalInfo();
const update = await Updater.checkForUpdate();

if (update.updateAvailable) {
  await Updater.downloadUpdate();
}

if (Updater.updateInfo()?.updateReady) {
  await Updater.applyUpdate();
}

Guidance:

• Keep release.baseUrl and artifact uploads aligned by channel/os/arch.
• Patching attempts incremental path first and falls back to full bundle when needed.

Utils

import { Utils } from "electrobun/bun";

Utils.moveToTrash(path);
Utils.showItemInFolder(path);
Utils.openExternal("https://example.com");
Utils.openPath("/path/to/file.pdf");

const paths = await Utils.openFileDialog({
  startingFolder: Utils.paths.home,
  allowedFileTypes: "png,jpg",
  canChooseFiles: true,
  canChooseDirectory: false,
  allowsMultipleSelection: true,
});

const { response } = await Utils.showMessageBox({
  type: "question",
  title: "Confirm",
  message: "Continue?",
  buttons: ["Yes", "No"],
  defaultId: 1,
  cancelId: 1,
});

Utils.showNotification({ title: "Done", body: "Task complete", silent: false });
Utils.clipboardWriteText("hello");
const text = Utils.clipboardReadText();
const formats = Utils.clipboardAvailableFormats();

Utils.quit();

Persistence paths:

• Utils.paths.userData
• Utils.paths.userCache
• Utils.paths.userLogs

Do not write runtime data into bundle resource paths.

GlobalShortcut

import { GlobalShortcut } from "electrobun/bun";

GlobalShortcut.register("CommandOrControl+Shift+Space", () => {
  console.log("shortcut fired");
});

GlobalShortcut.isRegistered("CommandOrControl+Shift+Space");
GlobalShortcut.unregister("CommandOrControl+Shift+Space");
GlobalShortcut.unregisterAll();

Screen

import { Screen } from "electrobun/bun";

const primary = Screen.getPrimaryDisplay();
const all = Screen.getAllDisplays();
const cursor = Screen.getCursorScreenPoint();

Session

import { Session } from "electrobun/bun";

const session = Session.fromPartition("persist:myapp");
// or Session.defaultSession

const cookies = session.cookies.get({ domain: "example.com" });
session.cookies.set({ name: "token", value: "abc", domain: "example.com", secure: true });
session.cookies.remove("https://example.com", "token");
session.cookies.clear();
session.clearStorageData(["cookies", "localStorage"]);

Use explicit partition naming for account isolation and predictable cookie/storage behavior.

Window and Webview APIs

Contents

• BrowserWindow constructor and common methods
• BrowserView methods and events
• <electrobun-webview> tag
• Navigation rules and event behavior

BrowserWindow

import { BrowserWindow } from "electrobun/bun";

const win = new BrowserWindow({
  title: "My App",
  url: "views://mainview/index.html",
  frame: { width: 1200, height: 800, x: 100, y: 100 },
  titleBarStyle: "default", // "default" | "hidden" | "hiddenInset"
  transparent: false,
  sandbox: false,            // use true for untrusted content
  partition: "persist:main",
  preload: "views://mainview/preload.js",
  rpc: myRPC,
  styleMask: {
    Titled: true,
    Closable: true,
    Miniaturizable: true,
    Resizable: true,
  },
});

Common methods:

• setTitle, close, focus
• minimize / unminimize / isMinimized
• maximize / unmaximize / isMaximized
• setFullScreen / isFullScreen
• setAlwaysOnTop / isAlwaysOnTop
• setPosition, setSize, setFrame
• getFrame, getPosition, getSize

Window events:

• close
• resize
• move
• focus

Default webview:

const webview = win.webview;

BrowserView

Access patterns:

• win.webview
• BrowserView.getById(id)
• BrowserView.getAll()
• new BrowserView({...}) for advanced use cases

import { BrowserView } from "electrobun/bun";

webview.loadURL("views://mainview/page.html");
webview.loadHTML({ html: "<h1>Hello</h1>" });
webview.executeJavascript('document.title = "new"');
webview.openDevTools();
webview.closeDevTools();
webview.toggleDevTools();
webview.findInPage("search term", { forward: true, matchCase: false });
webview.stopFindInPage();

Navigation rules:

webview.setNavigationRules([
  "^*",                    // block all
  "*://trusted.com/*",     // allow trusted.com
  "^http://*",             // block non-HTTPS
]);

Rule semantics:

• Glob-style patterns
• Prefix ^ means block rule
• Last matching rule wins
• If no rule matches, navigation is allowed

Built-in RPC helper:

const title = await webview.rpc.request.evaluateJavascriptWithResponse({
  script: "document.title",
});

BrowserView events:

• will-navigate
• did-navigate
• did-navigate-in-page
• did-commit-navigation
• dom-ready
• new-window-open
• download-started
• download-progress
• download-completed
• download-failed

will-navigate note:

• Navigation allow/block decision is made in native code based on setNavigationRules.
• Event is informational by the time it fires.

<electrobun-webview> (OOPIF)

Custom tag for process-isolated nested webviews.

<electrobun-webview
  id="child-webview"
  src="https://example.com"
  partition="persist:isolated"
  sandbox
  style="width: 100%; height: 500px;"
></electrobun-webview>

Common attributes:

• src, html, preload, partition, sandbox
• transparent, hidden, passthroughEnabled, delegateMode

Common methods:

• loadURL, goBack, goForward, reload
• canGoBack, canGoForward
• setNavigationRules
• callAsyncJavaScript
• on, off

Host messaging from preload:

// preload script in nested webview context
window.__electrobunSendToHost({ type: "click", x: 10, y: 20 });

// host page
document
  .getElementById("child-webview")
  .on("host-message", (e) => console.log(e.detail));

Security posture for nested webviews:

• Use sandbox for untrusted content.
• Add explicit navigation allowlists.
• Validate all host-message payloads.