Home › Electron › Electron app Windsurf rules

Electron app Windsurf rules

Windsurf rules for secure Electron 44 apps: context isolation, preload bridges, typed IPC, and packaging.

WindsurfElectron

How to use

Save this as .windsurf/rules/electron.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

---
trigger: glob
globs: src/main/**,src/preload/**,src/renderer/**,electron/**
---

# Electron (44)

## Process boundaries
- Main process (`src/main`): windows, native APIs, file system, IPC handlers. Renderer (`src/renderer`): UI only, no Node access.
- Keep defaults: `contextIsolation: true`, `sandbox: true`, `nodeIntegration: false`. Never turn them off.
- The preload script exposes a minimal, typed API with `contextBridge.exposeInMainWorld('api', {...})`. Expose specific functions (`api.openFile()`), never `ipcRenderer` itself.

## IPC
- Request/response via `ipcRenderer.invoke` + `ipcMain.handle`; channel names are constants shared in `src/shared/ipc.ts` with typed payloads.
- Validate every argument in the main process and check `event.senderFrame` origin for sensitive handlers.

## Security
- Strict Content-Security-Policy; load the app from `file://` or a custom protocol, not remote URLs.
- Block unexpected navigation (`will-navigate`) and new windows (`setWindowOpenHandler`), opening external links with `shell.openExternal` after an allowlist check.
- No `remote` module, no `eval`, no `webSecurity: false`.

## Packaging
- Build with the existing tool (Electron Forge or electron-builder); keep native deps rebuilt for the Electron ABI.
- Auto-update only over HTTPS with signed builds.

## Done when
Typecheck, lint and unit tests pass, and `npm run make` (or `npm run build`) produces an app that launches.