electrobun-platform

name	Electrobun Platform
description	Cross-platform specifics for Electrobun apps — platform support matrix, Linux/Windows/macOS behavioral differences, CEF requirements by platform, events API, security patterns, CI release matrix, artifact naming, and common pitfalls. Use when targeting multiple platforms, handling platform-specific bugs, setting up CI, or understanding webview differences.
version	1.0.0

Electrobun Cross-Platform Reference

Platform Support Matrix

Platform	OS value	Arch	Status	Default Webview
macOS ARM64	macos	arm64	Stable	WKWebView
macOS Intel	macos	x64	Stable	WKWebView
Windows x64	win	x64	Stable	WebView2 (Edge)
Windows ARM64	win	arm64	Via emulation	Runs x64 binary
Linux x64	linux	x64	Stable	GTKWebKit
Linux ARM64	linux	arm64	Stable	GTKWebKit

Build each platform on its native OS — no cross-compilation.

Linux — Always Bundle CEF

GTKWebKit has severe limitations:

• No webview layering (no overlapping webviews)
• No masking
• No <electrobun-webview> compositing
• Renderer mixing not supported — all webviews must use same renderer

For anything beyond a single-webview app on Linux:

// electrobun.config.ts
build: {
  linux: { bundleCEF: true, defaultRenderer: 'cef' },
}

Windows — Console Output

Production Windows builds use the GUI subsystem — no console for end users.

set ELECTROBUN_CONSOLE=1
.\MyApp.exe

Has no effect on macOS or Linux. Dev builds auto-attach a console.

Webview Hidden/Passthrough Behavior

// macOS: hidden and passthrough are INDEPENDENT
webviewSetHidden(webviewId, true);       // hidden, still intercepts clicks
webviewSetPassthrough(webviewId, true);  // separate call for click-through

// Windows & Linux: hidden = hidden + passthrough automatically
webviewSetHidden(webviewId, true);       // hidden AND clicks pass through
// webviewSetPassthrough() is a no-op on Windows/Linux

<electrobun-webview> HTML Tag (OOPIF)

Process-isolated "super iframes" — positioned by DOM, rendered natively. Requires CEF on Linux.

<electrobun-webview
  src="https://example.com"
  width="100%"
  height="400px"
  renderer="cef">
</electrobun-webview>

Access from bun: BrowserView.getAll() includes OOPIFs.

CEF Version Override

build: {
  cefVersion: '144.0.11+ge135be2+chromium-144.0.7559.97',
}

Same major = safe. Adjacent major = usually fine. Distant majors = higher risk.

Chromium Flags (CEF only)

build: {
  mac: {
    bundleCEF: true,
    chromiumFlags: {
      'show-paint-rects': true,
      'user-agent': 'MyApp/1.0',
      'disable-web-security': true,
    },
  },
}

Per-Window Renderer Override

// Override defaultRenderer per window
const win = new BrowserWindow({ url: '...', renderer: 'native' });
const cefWin = new BrowserWindow({ url: '...', renderer: 'cef' });

Mixing allowed on macOS and Windows. Not allowed on Linux.

Events API

import Electrobun from 'electrobun/bun';

// App lifecycle
Electrobun.events.on('before-quit', (e) => {
  if (hasUnsavedChanges()) e.response = { allow: false }; // cancel quit
});
Electrobun.events.on('open-url', (e) => {
  const url = new URL(e.data.url); // macOS URL scheme deep links
});

// Window events (global — all windows)
Electrobun.events.on('close', (e) => { /* e.data.id */ });
Electrobun.events.on('resize', (e) => { /* e.data.id, width, height */ });
Electrobun.events.on('move', (e) => { /* e.data.id, x, y */ });
Electrobun.events.(,  {  });
..(,  {  });


..(,  {  });
..(,  {  });
..(,  {  });

Quit trigger sources: dock icon, Cmd+Q, Ctrl+C, SIGTERM, window close, Utils.quit(), process.exit() — all route through before-quit.

Linux caveat: system-initiated quit paths (window-manager close, taskbar) may bypass before-quit. Utils.quit() and process.exit() are reliable.

URL Schemes / Deep Linking

macOS only. App must be in /Applications or ~/Applications.

// electrobun.config.ts
app: { urlSchemes: ['myapp', 'myapp-dev'] }

// src/bun/index.ts
Electrobun.events.on('open-url', (e) => {
  const url = new URL(e.data.url);
  if (url.pathname.startsWith('/auth')) { /* handle */ }
});

Windows/Linux URL schemes not yet supported.

Security Checklist

• sandbox: true on any BrowserView loading untrusted URLs — disables RPC, events still work
• setNavigationRules to allowlist permitted navigation targets; last match wins
• Never expose electrobun/bun APIs to sandboxed views — route through RPC with validation
• Use separate partition values per account for session isolation
• Prefer views:// over file:// for local assets

Code Signing (macOS)

One-Time Setup

1. Install full Xcode from App Store (not CLI tools alone — avoids expired cert issues)
2. Xcode → Settings → Accounts → add Apple ID → Manage Certificates → + → Developer ID Application
3. Apple Developer Portal: Identifiers → register bundle ID
4. account.apple.com: App Specific Passwords → create one

Required Env Vars

export ELECTROBUN_DEVELOPER_ID="My Corp Inc. (BGU899NB8T)"
export ELECTROBUN_TEAMID="BGU899NB8T"
export ELECTROBUN_APPLEID="[e-mail]"
export ELECTROBUN_APPLEIDPASS="xxxx-xxxx-xxxx-xxxx"

Unsigned apps show "damaged and can't be opened" — users fix with:

xattr -cr /Applications/YourApp.app

Entitlements

build: {
  mac: {
    entitlements: {
      'com.apple.security.device.camera': 'Needed for video',
      'com.apple.security.device.microphone': 'Needed for audio',
    }
  }
}

Application Icons

build: {
  mac: { icons: 'icon.iconset' },
  // icon.iconset/ must contain icon_{16,32,64,128,256,512}x{same}[@2x].png
  win: { icon: 'icon.iconset/icon_256x256.png' }, // .ico or .png, auto-converted
  linux: { icon: 'icon.iconset/icon_256x256.png' }, // 256x256+ .png
}

Reuse PNGs from the macOS iconset for Windows/Linux — no separate files needed.

Artifact Naming Convention

Artifacts use {channel}-{os}-{arch}- prefix. Stable omits the channel. App name spaces stripped.

canary-macos-arm64-MyApp-canary.dmg
canary-macos-arm64-MyApp-canary.app.tar.zst
canary-macos-arm64-{prevHash}.patch
canary-win-x64-MyApp-Setup-canary.zip
canary-win-x64-MyApp-canary.tar.zst
canary-linux-x64-MyAppSetup-canary.tar.gz
stable-macos-arm64-MyApp.dmg     ← no "stable" in name on stable channel

Keep old patches on your static host — users >1 version behind auto-fall back to full .tar.zst.

Release Hosting

Static file host — no server required: S3, Cloudflare R2, GCS, GitHub Releases.

release: {
  baseUrl: 'https://storage.googleapis.com/mybucket/myapp/',
  // GitHub Releases:
  // baseUrl: 'https://github.com/ORG/REPO/releases/latest/download',
}

GitHub Releases limitation: /releases/latest/download skips prereleases. Stable works; canary auto-updates will NOT — use R2/S3 for canary channel.

CI Build Matrix (GitHub Actions)

Each platform must build on its own native runner:

jobs:
  build-macos-arm64:
    runs-on: macos-14          # Apple Silicon
  build-macos-x64:
    runs-on: macos-13          # Intel
  build-windows:
    runs-on: windows-latest
  build-linux:
    runs-on: ubuntu-latest

# Each job:
#   uses: actions/checkout@v4
#   uses: oven-sh/setup-bun@v2
#   run: bun install
#   run: electrobun build --env=stable
#   uses: softprops/action-gh-release@v1
#     with: files: artifacts/*

Tag naming convention: tags containing -canary → canary build; all others → stable.

ASAR Packaging

build: {
  useAsar: true,
  asarUnpack: ['*.node', '*.dll', '*.dylib', '*.so', 'data/large/**/*'],
}

Packs app resources into app.asar. Unpacked files → app.asar.unpacked/. Benefits: faster I/O, code obfuscation via randomized temp paths.

Common Pitfalls

Issue	Fix
Linux webview layering broken	bundleCEF: true + defaultRenderer: 'cef'
Canary auto-update not working	GitHub /releases/latest skips prereleases — use R2/S3
"damaged and can't be opened" macOS	Enable codesign + notarize, or xattr -cr for testing
Code signing cert errors	Install full Xcode from App Store, not just CLI tools
RPC type mismatch at runtime	Confirm shared type file is imported by both sides
Sandbox webview + RPC silent failure	sandbox: true disables RPC — use events or remove sandbox
Windows no console output	Set ELECTROBUN_CONSOLE=1 env var
URL schemes not registering	App must be in /Applications, macOS only
Cross-compilation attempt	Each platform must build on its own native OS
Linux renderer mixing	All webviews must use the same renderer on Linux
Old patches missing	Keep all patch files on static host for sequential upgrades
before-quit not firing on Linux	System-initiated quits may bypass it; Utils.quit() is reliable
Notarize + codesign disabled for speed	Turn off during rapid debug cycles, re-enable for release