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
; 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 : "Hello
" } ) ; // 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