Electron

---
name: Electron
description: Build Electron desktop apps with secure architecture and common pitfall avoidance.
metadata: {"clawdbot":{"emoji":"⚡","requires":{"bins":["npm"]},"os":["linux","darwin","win32"]}}
---

## Security Non-Negotiables
- `nodeIntegration: false` is mandatory — renderer with Node.js access means XSS = full system compromise
- `contextIsolation: true` is mandatory — separates preload context from renderer
- Whitelist IPC channels explicitly — never forward arbitrary channel names from renderer
- Validate all IPC message content — renderer is untrusted, treat like external API input
- Never use `eval()` or `new Function()` in renderer — defeats all security boundaries

## Preload Script Rules
- `contextBridge.exposeInMainWorld()` is the only safe bridge — raw `ipcRenderer` exposure is vulnerable
- Clone data before passing across bridge — prevents prototype pollution attacks
- Minimal API surface — expose specific functions, not generic send/receive

## Architecture Traps
- `webPreferences` locked after window creation — can't enable nodeIntegration later
- Blocking main process freezes ALL windows — async everything, no sync file operations
- Each BrowserWindow is separate renderer process — can't share JS variables directly
- `show: false` then `ready-to-show` — prevents white flash, looks more native

## Native Module Pain
- Pre-built native modules won't work — must rebuild for Electron's specific Node version
- `electron-rebuild` after every Electron upgrade — version mismatch = runtime crash
- N-API modules more stable — survive Electron upgrades better than nan-based

## Packaging Pitfalls
- Dev dependencies included by default — production builds bloat without explicit exclusion
- Code signing required for macOS auto-update — unsigned apps can't use Squirrel
- Windows notifications require `app.setAppUserModelId()` — silent failure without it
- ASAR isn't encryption — source readable with simple tools, don't rely on it for secrets

## Platform-Specific Issues
- CORS blocks `file://` protocol — use custom protocol (`app://`) or local server
- Windows needs NSIS or Squirrel for auto-update — installer format matters
- macOS universal binary needs `--universal` flag — ships both Intel and ARM

## Memory and Performance
- Unclosed windows leak memory — call `win.destroy()` explicitly when done
- Lazy load heavy modules — startup time directly affects perceived quality
- `backgroundThrottling: false` if timers matter when minimized

## Debugging
- Main process: `--inspect` flag, connect via `chrome://inspect`
- Renderer: `webContents.openDevTools()` or keyboard shortcut
- `electron-log` for persistent logs — console.log vanishes on restart