fantomsuj/electron-wrapper

Electron Wrapper for Bun Web Apps

This skill guides wrapping an existing Bun web server into a native desktop app using Electron. It's based on a proven implementation that solved every major integration challenge.

Architecture

"Electron as chrome, Bun as server" — Two runtimes working together:

• Electron/Node.js handles window management, native menus, auto-updates, and IPC
• Bun runs the actual web server with all your application logic

The Electron main process spawns a bundled Bun binary that runs your server, then loads http://localhost:{port} in a BrowserWindow. Your web app doesn't know or care that it's inside Electron — it's just a web page with an optional window.electronAPI bridge for native features.

This architecture means:

• Zero changes to your server code (it's still a standard Bun HTTP server)
• The web app works identically in a browser or in Electron
• Electron handles only what browsers can't: window chrome, system tray, auto-updates, file system access
• Two separate node_modules — Electron uses npm, your web app uses Bun

Phase 1: Project Setup

Create the Electron subproject alongside your existing Bun web app.

What to create:

• electron/ directory with its own package.json (npm, not Bun), two tsconfigs (ESM for main, CJS for preload), electron-builder.yml, and macOS entitlements
• scripts/build-server.ts for bundling the server
• scripts/download-bun.ts for downloading platform-specific Bun binaries
• Parent project changes: new scripts, tsconfig excludes, .gitignore entries

Reference: project-setup.md

Phase 2: Main Process

Build the Electron main process — the entry point, server spawning, window management, auto-updater, and preload bridge.

Files to create:

| File | Purpose | |------|---------| | electron/src/main/index.ts | App lifecycle, dev/prod mode, single-instance lock, IPC handlers | | electron/src/main/bun-server.ts | Spawn bundled Bun, port selection, health polling, env var injection | | electron/src/main/window.ts | BrowserWindow config, bounds persistence, security settings, navigation guards | | electron/src/main/updater.ts | electron-updater setup, event forwarding to renderer | | electron/src/preload/index.ts | contextBridge API with invoke/on patterns and unsubscribe support |

Key decisions:

• Dev mode uses ELECTRON_DEV_URL env var to connect to the external dev server (no internal Bun spawn)
• autoDownload: false — let users choose when to download updates
• Preload exposes only specific methods, never raw ipcRenderer
• Window persists bounds via electron-store

Reference: main-process.md

Phase 3: Web App Adaptation

Adapt the existing web app to detect and respond to the Electron environment while remaining fully functional as a standalone web app.

Changes to the web app:

| Change | Details | |--------|---------| | Electron detection utility | isElectron(), getElectronPlatform(), isMacElectron(), applyElectronDocumentAttributes() | | Type declarations | window.electronAPI with all properties optional | | CSS drag regions | .app-window-drag/.app-window-no-drag classes, auto-exclude interactive elements | | Traffic light spacing | --electron-traffic-left CSS variable (72px on macOS, 0px elsewhere) | | Storage path | Env var for data directory, falling back to CWD | | Static asset serving | Env var for static dir in production mode | | Auto-update hook | useElectronUpdater() React hook with download/install controls | | Update notification | Pill component showing available → downloading → ready states | | Feature gating | Disable demo mode, hosted features when in Electron |

Reference: web-adaptation.md

Phase 4: Build & Distribution

Bundle everything, set up CI/CD, and handle code signing.

Build pipeline:

1. Build web app (bun run build)
2. Bundle server to single file (Bun.build() → resources/server/index.js)
3. Download platform-specific Bun binaries → resources/bun/{platform}-{arch}/
4. Compile Electron TypeScript (two passes: main ESM + preload CJS)
5. electron-builder packages everything with extraResources

CI/CD:

• GitHub Actions triggered by version tags (e.g., v*, clippy-v*)
• Matrix builds: macOS arm64/x64 on macos-14, Windows x64 on windows-latest
• --publish never in build step, separate publish job creates draft GitHub release
• Apple certificate import and notarization in CI

Code signing:

• macOS: Developer ID Application certificate, exported as base64 .p12
• Notarization via Apple ID + app-specific password
• 5 GitHub secrets required: APPLE_CERTIFICATE, APPLE_CERTIFICATE_PASSWORD, APPLE_ID, APPLE_PASSWORD, APPLE_TEAM_ID

Icons:

• macOS: sips + iconutil from source PNG → .icns
• Windows: png-to-ico npm package → .ico

Reference: build-and-distribute.md

Cutting a Release

Never build release artifacts locally. CI has the signing certificates and notarization credentials. Local builds produce unsigned apps that macOS Gatekeeper will block.

Release workflow:

1. Bump version in electron/package.json, commit, and merge to main
2. Find the tag pattern the CI workflow expects:

   grep -A2 'tags:' .github/workflows/*.yml
   

3. Tag the merged commit on main:

   git tag <pattern><version> origin/main
   git push origin <pattern><version>
   

4. Monitor CI:

   gh run list --workflow=<workflow>.yml --limit=1
   

5. Review and publish the draft release on GitHub

Common mistakes:

• Running electron-builder --publish always locally — no notarization
• Using gh release create with local artifacts — unsigned
• Tagging before the version bump is merged — wrong version in build
• Tagging a feature branch instead of origin/main

See pitfalls.md §13 for full details.

Critical Pitfalls

Quick-reference list — see pitfalls.md for full details with symptoms and code examples.

| # | Pitfall | One-line fix | |---|---------|-------------| | 1 | ESM/CJS conflicts | "type": "module" + default import pattern for CJS packages | | 2 | Preload must be CJS | Separate tsconfig with "module": "CommonJS" | | 3 | __dirname unavailable | fileURLToPath(import.meta.url) polyfill | | 4 | Dev mode MIME errors | Connect to external dev server via ELECTRON_DEV_URL | | 5 | Bun version mismatch | Pin version in download script, match dev version | | 6 | nvm PATH issues | bash -lc for spawned processes | | 7 | Wrong storage path | Env var + app.getPath("userData") | | 8 | White flash on open | show: false + ready-to-show + dark backgroundColor | | 11 | ${platform} != process.platform | Put Bun extraResources in mac:/win: sections with darwin-/win32- prefixes | | 12 | Bun workspace hoists deps | Bundle main with esbuild + createRequire banner, or use npm for electron dir | | 13 | Local builds aren't notarized | Always release via CI tags, never electron-builder --publish locally |

Dev Workflow

The electron:dev command runs the full development environment:

npm run dev
  ├── concurrently
  │   ├── dev:web    → cd .. && bun run dev          (Bun dev server with HMR)
  │   └── dev:electron
  │       ├── wait-on http://localhost:3005           (wait for dev server)
  │       ├── npm run build                           (compile TS)
  │       └── ELECTRON_DEV_URL=... electron .         (launch Electron)

• The web dev server runs with HMR — changes reflect instantly
• Electron connects to the dev server instead of spawning its own Bun
• Preload and main process changes require restarting electron:dev
• Web app changes hot-reload automatically

To test production-like behavior locally:

bun run electron:pack    # builds everything, packages without installer
# Output in electron/release/

Customization Checklist

When adapting this for a new project, update these project-specific values:

• [ ] App name in electron-builder.yml (productName, appId)
• [ ] Window title in window.ts
• [ ] Dev server port in dev:electron script and dev script
• [ ] Environment variable names (e.g., APP_DATA_DIR, APP_STATIC_DIR)
• [ ] backgroundColor in window config to match your app's theme
• [ ] category in electron-builder.yml mac section
• [ ] Repository URL in electron/package.json
• [ ] Bun version in download-bun.ts
• [ ] Icon assets in electron/assets/