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: // 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: 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: 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: 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 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 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: 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: 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: 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