Home › Electron › Electron app AGENTS.md

Electron app AGENTS.md

AGENTS.md for Electron desktop apps (Electron Forge or electron-vite): process layout, IPC contracts, and release safety.

AGENTS.mdElectron

How to use

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

# AGENTS.md: Electron app

## Commands
`npm run dev` · `npm test` · `npm run lint` · `npm run typecheck` · package: `npm run make` (don't publish)

## Layout
- `src/main/` (Node, privileged), `src/preload/` (bridge), `src/renderer/` (web UI, unprivileged), `src/shared/` (types and IPC channel names).
- Renderer code may not import `electron`, `fs`, or other Node modules. If it needs something, add a typed method to the preload API and a handler in main.

## IPC contract
- Each channel is defined once in `src/shared/ipc.ts` with request/response types.
- Main: `ipcMain.handle(CHANNEL, handler)`; handlers validate input (zod) and return plain serializable data.
- Preload: `contextBridge.exposeInMainWorld('api', { getSettings: () => ipcRenderer.invoke(...) })` and a matching `window.api` type declaration.

## Security (keep these on)
- `contextIsolation`, `sandbox`, no `nodeIntegration`, strict CSP, navigation and `window.open` blocked except allowlisted URLs.
- Never load remote code into a window with preload access.

## Native and files
- Use `app.getPath('userData')` for app data; never write next to the executable.
- Native modules must be rebuilt for Electron (`@electron/rebuild` or the bundler plugin).

## Don't
- Don't bump the Electron major, change signing/notarization config, or publish releases without approval.

## Done
Typecheck, lint and tests pass; the packaged app launches and the changed flow works.