Electron

---
name: electron
description: Cross-platform desktop applications with web technologies (Chromium + Node.js)
layer: domain
category: desktop
triggers:
  - "electron app"
  - "desktop app"
  - "BrowserWindow"
  - "ipcMain"
  - "ipcRenderer"
  - "electron-builder"
  - "contextBridge"
  - "preload script"
linksTo:
  - react
  - typescript-frontend
  - nodejs
  - pwa
linkedFrom:
  - code-writer
riskLevel: medium
---

# Electron

Framework for building cross-platform desktop applications using Chromium and Node.js. Ships a single codebase as native apps for macOS, Windows, and Linux.

## When to Use

- Desktop apps needing OS-level access (file system, tray, notifications)
- Wrapping an existing web app as a native desktop experience
- Offline-first apps with local data storage
- Cross-platform tools where native UI per-platform is not justified

## Key Patterns

**Main vs Renderer Process** — Main process (Node.js) manages windows, system APIs, and app lifecycle. Renderer processes (Chromium) handle UI. Never run privileged code in the renderer.

**IPC Communication** — Use `contextBridge.exposeInMainWorld()` in preload scripts to expose APIs safely. Communicate via `ipcMain.handle()` / `ipcRenderer.invoke()` (async) or `ipcMain.on()` / `ipcRenderer.send()` (fire-and-forget).

**Security Model** — Always enable `contextIsolation: true` and `sandbox: true`. Never set `nodeIntegration: true` in production. Validate all IPC inputs in main process. Use `safeStorage` for sensitive data.

**BrowserWindow Configuration** — Set `webPreferences.preload` to a dedicated preload script. Use `minWidth`/`minHeight` for sizing constraints. Enable `titleBarStyle: 'hiddenInset'` on macOS for frameless look.

**Auto-Update** — Use `electron-updater` with `autoUpdater.checkForUpdatesAndNotify()`. Publish to GitHub Releases or a private feed. Sign builds for macOS (notarization) and Windows (code signing).

**Tray & Menu System** — Create `Tray` in main process. Build menus with `Menu.buildFromTemplate()`. Use `nativeImage` for icons.

**Native File System** — Use `dialog.showOpenDialog()` / `dialog.showSaveDialog()` from main process, exposed via IPC. Never give renderer direct `fs` access.

**Packaging (electron-builder)** — Configure in `package.json` or `electron-builder.yml`. Target `dmg`+`zip` (macOS), `nsis` (Windows), `AppImage`+`deb` (Linux). Use `files` array to control included resources.

**Protocol Handlers** — Register custom protocols with `protocol.handle('app', handler)` for loading local resources securely instead of `file://` URLs.

**Context Isolation** — Always pair `contextIsolation: true` with a preload script. The preload runs in an isolated context with access to Node.js APIs but exposes only explicit bindings to the renderer.

## Anti-Patterns

| Anti-Pattern | Why It's Bad | Fix |
|---|---|---|
| `nodeIntegration: true` | RCE via XSS | Use preload + contextBridge |
| Bundling unused locales | +40MB app size | Exclude via electron-builder config |
| Synchronous IPC (`sendSync`) | Blocks renderer, freezes UI | Use async `invoke`/`handle` |
| No code signing | OS warnings, update fails | Sign + notarize all builds |
| Single BrowserWindow for all | Memory bloat, no isolation | Separate windows for heavy features |
| Secrets in renderer | Exposed via DevTools | Use `safeStorage` in main process |