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.