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