name: Electrobun Dev description: Use when running Electrobun in development mode — electrobun dev, --watch flag, hot reload, CEF devtools, debugging the renderer, or understanding the dev build cycle. version: 1.0.0

Electrobun Dev Mode

Commands

electrobun dev          # build (dev env) once, then launch app
electrobun dev --watch  # build, launch, then watch for changes and rebuild+relaunch

Shorthand via package.json (standard templates):

bun start               # → electrobun dev
bun run dev             # → electrobun dev --watch

What Happens on electrobun dev

1. Reads electrobun.config.ts
2. Downloads any missing native binaries (Bun, launcher, WGPU/CEF if configured)
3. Bundles build.bun.entrypoint via Bun.build() in dev mode (no minify, sourcemaps inline)
4. Bundles each build.views.* entrypoint
5. Copies build.copy files to build output
6. Skips codesign and notarization
7. Writes app bundle to build/dev-<os>-<arch>/
8. Launches the app, streaming stdout/stderr to your terminal

Watch Mode (--watch)

After initial build+launch, watch mode monitors:

• Dir containing build.bun.entrypoint
• Dir(s) containing each build.views.* entrypoint
• Dirs listed in build.watch (extra paths)
• Dirs of files listed in build.copy

Debounce: 300ms — rapid saves are coalesced into one rebuild.

Ignored automatically: build/, artifacts/, node_modules/, and patterns in build.watchIgnore.

On change: kills running app → rebuilds → relaunches.

Extra watch paths

// electrobun.config.ts
build: {
  watch: ["src/shared/", "assets/"],
  watchIgnore: ["src/**/*.test.ts", "src/**/*.spec.ts"],
}

CEF DevTools (Chromium inspector)

When using renderer: "cef" or defaultRenderer: "cef", the CEF renderer exposes Chrome DevTools at:

http://localhost:9222

Open in any Chrome/Chromium browser while the app is running. Lists all active renderer pages — click to inspect.

Note: DevTools are only available in dev builds. They are not exposed in canary or stable.

Native WebView Debugging (macOS)

For renderer: "native" (WKWebView), enable the developer extras:

// In src/bun/index.ts — call openDevTools() on the BrowserView instance
const view = new BrowserView({ ... });
view.openDevTools();  // Opens Safari Web Inspector (uses private WKWebView _inspector API)

Or in Safari: Develop → [Your App] → [webview name]

Debugging Tips

1. Console output: All console.log from bun-side code appears in the terminal. Renderer-side console.log only appears in devtools (not terminal).
2. RPC tracing: Add console.log to request/message handlers to trace cross-process calls.
3. Source maps: Dev builds include inline source maps. Stack traces point to .ts source lines.
4. Slow reload? Add only changed dirs to build.watch rather than broad patterns.
5. App not relaunching? If the app process is holding a file lock, kill it manually: pkill -f "<AppName>"

Build Output (dev)

build/dev-macos-arm64/
└── <AppName>-dev.app/
    └── Contents/
        ├── MacOS/
        │   ├── launcher          # native launcher
        │   └── main.js           # bundled bun entrypoint
        ├── Resources/
        │   ├── <viewname>/       # bundled renderer
        │   └── bun               # bun runtime binary
        └── Info.plist