electron-best-practices · diff
git:20260803.db14631 to git:20260803.88cd167
296 added, 1 removed. Audit A to A.
---
name: electron-best-practices
- description: "Guide AI agents through Electron app development with React including security patterns, type-safe IPC, React integration, packaging with code signing, and testing. Keywords: electron, electron-vite, electron-forge, contextBridge, IPC, security, react, packaging, code signing, notarization, playwright, desktop app." Use when building secure Electron apps with React/TypeScript (IPC, packaging, testing).
+ description: >-
+ Guide AI agents through Electron app development with React including security patterns,
+ type-safe IPC, React integration, packaging with code signing, and testing. Keywords:
+ electron, electron-vite, electron-forge, contextBridge, IPC, security, react, packaging,
+ code signing, notarization, playwright, desktop app. Use when building secure Electron
+ apps with React/TypeScript (IPC, packaging, testing).
---
+
+ # Electron + React Best Practices
+
+ Guide AI agents in building secure, production-ready Electron applications with React. This skill provides security patterns, type-safe IPC communication, project setup guidance, packaging and code signing workflows, and tools for analysis, scaffolding, and type generation.
+
+ ## When to Use This Skill
+
+ Use this skill when:
+ - Generating Electron main, preload, or renderer process code
+ - Configuring electron-vite or Electron Forge
+ - Setting up IPC communication between processes
+ - Implementing security patterns (contextBridge, sandbox, CSP)
+ - Packaging, signing, and notarizing desktop applications
+ - Testing Electron apps with Playwright
+ - Designing multi-window architectures
+
+ Do NOT use this skill when:
+ - Building Tauri apps (different paradigm, use Tauri-specific guidance)
+ - Building pure web apps with no desktop requirements
+ - Targeting Electron versions below 20 (security defaults differ)
+ - Using non-React renderer frameworks (use framework-specific skills)
+
+ ## Core Principles
+
+ ### 1. Security First Architecture
+
+ Modern Electron security relies on three defaults that became standard in Electron 20+: context isolation, sandbox mode, and nodeIntegration disabled. Disabling any of them allows XSS attacks to escalate to full remote code execution. All main-renderer communication must flow through contextBridge:
+
+ ```typescript
+ // preload.ts - SECURE pattern
+ contextBridge.exposeInMainWorld('electronAPI', {
+ loadPreferences: () => ipcRenderer.invoke('load-prefs'),
+ saveFile: (content: string) => ipcRenderer.invoke('save-file', content),
+ onUpdateCounter: (callback: (value: number) => void) => {
+ const handler = (_event: IpcRendererEvent, value: number) => callback(value);
+ ipcRenderer.on('update-counter', handler);
+ return () => ipcRenderer.removeListener('update-counter', handler);
+ }
+ });
+ ```
+
+ Set Content Security Policy via HTTP headers for apps loading local files, restricting script sources to `'self'`.
+
+ ### 2. Type-Safe IPC Communication
+
+ The invoke/handle pattern is preferred over send/on for request-response communication, providing proper async/await semantics and error propagation. For typed channels, use a mapped type pattern:
+
+ ```typescript
+ type IpcChannelMap = {
+ 'load-prefs': { args: []; return: UserPreferences };
+ 'save-file': { args: [content: string]; return: { success: boolean } };
+ };
+ ```
+
+ For complex applications, electron-trpc provides full type safety using tRPC's router pattern with Zod validation:
+
+ ```typescript
+ export const appRouter = t.router({
+ greeting: t.procedure
+ .input(z.object({ name: z.string() }))
+ .query(({ input }) => `Hello, ${input.name}!`),
+ });
+ ```
+
+ Error handling across the IPC boundary requires attention because Electron only serializes the `message` property of Error objects. Wrap responses in a `{ success, data, error }` result type to preserve full error context.
+
+ ### 3. Modern Project Setup
+
+ The recommended stack uses electron-vite for development and Electron Forge for packaging. electron-vite provides a unified configuration managing main, preload, and renderer processes with sub-second dev server startup and instant HMR. Electron Forge uses first-party Electron packages for signing and notarization.
+
+ ```
+ src/
+ ├── main/ # Main process (Node.js environment)
+ │ ├── index.ts
+ │ └── ipc/ # IPC handlers
+ ├── preload/ # Secure bridge via contextBridge
+ │ ├── index.ts
+ │ └── index.d.ts # TypeScript declarations for exposed APIs
+ └── renderer/ # React application (pure web, no Node access)
+ ├── src/
+ └── index.html
+ ```
+
+ ### 4. React Integration Patterns
+
+ React 18's concurrent features work normally in Electron's Chromium-based renderer. Strict Mode's double-invocation of effects catches IPC listener leaks that would otherwise cause memory issues. Always return cleanup functions from effects that register IPC listeners:
+
+ ```typescript
+ useEffect(() => {
+ const cleanup = window.electronAPI.onUpdateCounter((value) => {
+ setCount(value);
+ });
+ return cleanup;
+ }, []);
+ ```
+
+ For multi-window applications, the main process should serve as the single source of truth for shared state. Use electron-store for persistence combined with IPC broadcasting so any window's mutation updates all others.
+
+ ## Quick Reference
+
+ | Category | Prefer | Avoid |
+ |----------|--------|-------|
+ | Security | `contextBridge.exposeInMainWorld()` | `nodeIntegration: true` |
+ | IPC | `invoke/handle` pattern | `send/on` for request-response |
+ | Preload | Typed function wrappers | Exposing raw `ipcRenderer` |
+ | Build tool | electron-vite | webpack-based toolchains |
+ | Packaging | Electron Forge | Manual packaging |
+ | State | Zustand + electron-store | Redux for simple apps |
+ | Testing | Playwright E2E | Spectron (deprecated) |
+ | Updates | electron-updater | Manual update checks |
+ | Signing | CI-integrated code signing | Unsigned releases |
+ | CSP | HTTP headers, `'self'` only | No CSP |
+ | Error handling | Result type `{success, data, error}` | Raw Error across IPC |
+ | Multi-window | Main process as state hub | Direct window-to-window |
+
+ ## Code Generation Guidelines
+
+ When generating Electron code, follow these patterns:
+
+ ### BrowserWindow Creation
+
+ ```typescript
+ const win = new BrowserWindow({
+ webPreferences: {
+ preload: path.join(__dirname, '../preload/index.js'),
+ contextIsolation: true,
+ sandbox: true,
+ nodeIntegration: false,
+ },
+ });
+ ```
+
+ Always enable contextIsolation and sandbox. Never enable nodeIntegration. The preload path must resolve to the built output location.
+
+ ### IPC Handler Module
+
+ ```typescript
+ export function registerFileHandlers(): void {
+ ipcMain.handle('save-file', async (_event, content: string) => {
+ try {
+ await fs.writeFile(filePath, content);
+ return { success: true, data: filePath };
+ } catch (err) {
+ return { success: false, error: (err as Error).message };
+ }
+ });
+ }
+ ```
+
+ Group related handlers into modules. Use the result type pattern for all return values. Validate all arguments received from the renderer process.
+
+ ## Common Anti-Patterns
+
+ Avoid these patterns when generating Electron code:
+
+ | Anti-Pattern | Problem | Solution |
+ |--------------|---------|----------|
+ | `nodeIntegration: true` | XSS escalates to full RCE | Keep disabled (default) |
+ | Exposing `ipcRenderer` directly | Full IPC access from renderer | Wrap in contextBridge functions |
+ | Missing `contextIsolation` | Renderer accesses preload scope | Keep enabled (default since Electron 12) |
+ | No code signing | OS security warnings, Gatekeeper blocks | Sign and notarize for all platforms |
+ | `BrowserWindow` without sandbox | Preload has full Node.js access | Enable sandbox (default since Electron 20) |
+ | Unvalidated IPC arguments | Injection attacks from renderer | Validate with Zod or manual checks |
+ | `0.0.0.0` server binding | Network-exposed local server | Always bind to `127.0.0.1` |
+ | Missing CSP headers | Script injection vectors | Set strict CSP via HTTP headers |
+ | No IPC error serialization | Lost error context across boundary | Use Result type pattern |
+ | Spectron for testing | Deprecated, Electron 13 max | Use Playwright |
+
+ See `references/security/security-checklist.md` for the full security audit checklist.
+
+ ## Scripts Reference
+
+ ### analyze-security.ts
+
+ Analyze Electron projects for security misconfigurations:
+
+ ```bash
+ deno run --allow-read scripts/analyze-security.ts <path> [options]
+
+ Options:
+ --strict Enable all checks
+ --json Output JSON for CI
+ -h, --help Show help
+
+ Examples:
+ # Analyze a project
+ deno run --allow-read scripts/analyze-security.ts ./src
+
+ # Strict mode for CI pipeline
+ deno run --allow-read scripts/analyze-security.ts ./src --strict --json
+ ```
+
+ ### scaffold-electron-app.ts
+
+ Scaffold a new Electron + React project with secure defaults:
+
+ ```bash
+ deno run --allow-read --allow-write scripts/scaffold-electron-app.ts [options]
+
+ Options:
+ --name <name> App name (required)
+ --path <path> Target directory (default: ./)
+ --with-react Include React setup
+ --with-trpc Include electron-trpc
+ --with-tests Include Playwright tests
+
+ Examples:
+ # Basic app with React
+ deno run --allow-read --allow-write scripts/scaffold-electron-app.ts \
+ --name "my-app" --with-react
+
+ # Full setup with trpc and tests
+ deno run --allow-read --allow-write scripts/scaffold-electron-app.ts \
+ --name "my-app" --with-react --with-trpc --with-tests
+ ```
+
+ ### generate-ipc-types.ts
+
+ Generate TypeScript type definitions from IPC handler files:
+
+ ```bash
+ deno run --allow-read --allow-write scripts/generate-ipc-types.ts [options]
+
+ Options:
+ --handlers <path> Path to IPC handler files
+ --output <path> Output path for type definitions
+ --validate Validate existing types match handlers
+
+ Examples:
+ # Generate types from handlers
+ deno run --allow-read --allow-write scripts/generate-ipc-types.ts \
+ --handlers ./src/main/ipc --output ./src/preload/ipc-types.d.ts
+
+ # Validate types in CI
+ deno run --allow-read scripts/generate-ipc-types.ts \
+ --handlers ./src/main/ipc --validate
+ ```
+
+ ## Additional Resources
+
+ ### Security
+ - `references/security/context-isolation.md` - contextBridge and isolation patterns
+ - `references/security/csp-and-permissions.md` - Content Security Policy configuration
+ - `references/security/security-checklist.md` - Full security audit checklist
+
+ ### IPC Communication
+ - `references/ipc/typed-ipc.md` - Typed channel map patterns
+ - `references/ipc/electron-trpc.md` - tRPC integration for full type safety
+ - `references/ipc/error-serialization.md` - Result types across IPC boundary
+
+ ### Architecture
+ - `references/architecture/project-structure.md` - Directory organization
+ - `references/architecture/process-separation.md` - Main, preload, and renderer roles
+ - `references/architecture/multi-window-state.md` - Shared state across windows
+
+ ### React Integration
+ - `references/integration/react-patterns.md` - useEffect cleanup, Strict Mode
+ - `references/integration/state-management.md` - Zustand and electron-store patterns
+
+ ### Packaging & Distribution
+ - `references/packaging/code-signing.md` - Platform-specific signing workflows
+ - `references/packaging/auto-updates.md` - electron-updater configuration
+ - `references/packaging/bundle-optimization.md` - Size reduction techniques
+ - `references/packaging/ci-cd-patterns.md` - GitHub Actions matrix builds
+
+ ### Testing
+ - `references/testing/playwright-e2e.md` - Playwright Electron support
+ - `references/testing/unit-testing.md` - Jest/Vitest multi-project configuration
+ - `references/testing/test-structure.md` - Test organization patterns
+
+ ### Tooling
+ - `references/tooling/electron-vite.md` - Build tool configuration
+ - `references/tooling/electron-forge.md` - Packaging and distribution
+ - `references/tooling/tauri-comparison.md` - When to choose Tauri instead
+
+ ### Templates
+ - `assets/templates/main-process.ts.md` - Main process starter template
+ - `assets/templates/preload-script.ts.md` - Preload script with contextBridge
+ - `assets/templates/ipc-handler.ts.md` - IPC handler module template
+ - `assets/templates/react-root.tsx.md` - React root component template
+
+ ### Configuration Examples
+ - `assets/configs/electron-vite.config.ts.md` - electron-vite configuration
+ - `assets/configs/forge.config.js.md` - Electron Forge configuration
+ - `assets/configs/tsconfig.json.md` - TypeScript configuration presets
+ - `assets/configs/playwright.config.ts.md` - Playwright Electron test config
+
+ ### Complete Examples
+ - `assets/examples/typed-ipc-example.md` - End-to-end typed IPC walkthrough
+ - `assets/examples/multi-window-example.md` - Multi-window state management