electron-best-practices（Electron 最佳实践）

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

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:

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