electron-best-practices

Electron + React のベストプラクティス

AI エージェントが、安全で本番環境に対応できる Electron アプリケーションを React で構築できるようにするガイドです。このスキルでは、セキュリティパターン、型安全な IPC 通信、プロジェクトのセットアップ方法、パッケージ化とコード署名のワークフロー、分析・スキャフォールディング・型生成のためのツールを解説します。

このスキルを使用する場面

次の場合にこのスキルを使用してください：

• Electron のメイン、プリロード、またはレンダラープロセスのコードを生成する場合
• electron-vite または Electron Forge を設定する場合
• プロセス間の IPC 通信をセットアップする場合
• セキュリティパターン（contextBridge、サンドボックス、CSP）を実装する場合
• デスクトップアプリケーションをパッケージ化、署名、公証する場合
• Playwright で Electron アプリをテストする場合
• マルチウィンドウアーキテクチャを設計する場合

次の場合はこのスキルを使用しないでください：

• Tauri アプリを構築する場合（異なるパラダイムのため、Tauri 専用のガイダンスを使用してください）
• デスクトップ要件のない純粋な Web アプリを構築する場合
• Electron 20 未満を対象とする場合（セキュリティのデフォルト設定が異なります）
• React 以外のレンダラーフレームワークを使用する場合（フレームワーク固有のスキルを使用してください）

主な原則

1. セキュリティを最優先するアーキテクチャ

最新の Electron のセキュリティは、Electron 20 以降で標準となった 3 つのデフォルト設定、コンテキスト分離、サンドボックスモード、nodeIntegration の無効化に依存しています。これらのいずれかを無効にすると、XSS 攻撃が完全なリモートコード実行に発展するおそれがあります。メインプロセスとレンダラープロセス間の通信はすべて、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);
  }
});

ローカルファイルを読み込むアプリでは、HTTP ヘッダーを使って Content Security Policy を設定し、スクリプトのソースを 'self' に制限してください。

2. 型安全な IPC 通信

リクエストとレスポンスの通信では、適切な async/await のセマンティクスとエラー伝播が得られる invoke/handle パターンが、send/on よりも推奨されます。型付きチャンネルには、マップ型のパターンを使用してください：

type IpcChannelMap = {
  'load-prefs': { args: []; return: UserPreferences };
  'save-file': { args: [content: string]; return: { success: boolean } };
};

複雑なアプリケーションでは、electron-trpc を使用すると、Zod による検証を備えた tRPC のルーターパターンで完全な型安全性を実現できます：

export const appRouter = t.router({
  greeting: t.procedure
    .input(z.object({ name: z.string() }))
    .query(({ input }) => `Hello, ${input.name}!`),
});

Electron では Error オブジェクトの message プロパティのみがシリアライズされるため、IPC の境界を越えたエラー処理には注意が必要です。完全なエラーコンテキストを保持できるよう、レスポンスを { success, data, error } の結果型でラップしてください。

3. 最新のプロジェクトセットアップ

推奨スタックでは、開発に electron-vite、パッケージ化に Electron Forge を使用します。electron-vite はメイン、プリロード、レンダラープロセスを管理する統合設定を提供し、1 秒未満での開発サーバー起動と即時の HMR を実現します。Electron Forge は、署名と公証に Electron の公式パッケージを使用します。

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 統合パターン

React 18 の並行機能は、Electron の Chromium ベースのレンダラーでも通常どおり動作します。Strict Mode によるエフェクトの二重実行は、放置するとメモリの問題につながる IPC リスナーのリークを検出します。IPC リスナーを登録するエフェクトからは、必ずクリーンアップ関数を返してください：

useEffect(() => {
  const cleanup = window.electronAPI.onUpdateCounter((value) => {
    setCount(value);
  });
  return cleanup;
}, []);

マルチウィンドウアプリケーションでは、共有状態の唯一の信頼できる情報源として、メインプロセスを使用してください。永続化には electron-store を使い、IPC によるブロードキャストと組み合わせることで、いずれかのウィンドウでの変更がほかのすべてのウィンドウに反映されるようにします。

クイックリファレンス

カテゴリ	推奨	避ける
セキュリティ	contextBridge.exposeInMainWorld()	nodeIntegration: true
IPC	invoke/handle パターン	リクエストとレスポンスに send/on を使う
プリロード	型付き関数ラッパー	ipcRenderer をそのまま公開する
ビルドツール	electron-vite	webpack ベースのツールチェーン
パッケージ化	Electron Forge	手動でのパッケージ化
状態管理	Zustand + electron-store	シンプルなアプリで Redux を使う
テスト	Playwright E2E	Spectron（非推奨）
更新	electron-updater	手動での更新チェック
署名	CI に統合したコード署名	未署名のリリース
CSP	HTTP ヘッダー、'self' のみ	CSP を設定しない
エラー処理	結果型 {success, data, error}	IPC を介して Error をそのまま渡す
マルチウィンドウ	状態のハブとしてのメインプロセス	ウィンドウ間の直接通信

コード生成のガイドライン

Electron のコードを生成する際は、次のパターンに従ってください：

BrowserWindow の作成

const win = new BrowserWindow({
  webPreferences: {
    preload: path.join(__dirname, '../preload/index.js'),
    contextIsolation: true,
    sandbox: true,
    nodeIntegration: false,
  },
});

contextIsolation と sandbox は必ず有効にしてください。nodeIntegration は決して有効にしないでください。preload のパスはビルド後の出力先を指す必要があります。

IPC ハンドラーモジュール

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 };
    }
  });
}

関連するハンドラーをモジュールにまとめてください。すべての戻り値に Result 型パターンを使用してください。レンダラープロセスから受け取るすべての引数を検証してください。

よくあるアンチパターン

Electron コードを生成する際は、次のパターンを避けてください。

アンチパターン	問題	解決策
nodeIntegration: true	XSS が完全な RCE に発展します	無効のままにします（デフォルト）
ipcRenderer を直接公開する	レンダラーから IPC に完全にアクセスできてしまいます	contextBridge 関数でラップします
contextIsolation がない	レンダラーが preload のスコープにアクセスします	有効のままにします（Electron 12 以降はデフォルト）
コード署名がない	OS のセキュリティ警告が表示され、Gatekeeper にブロックされます	すべてのプラットフォームで署名と公証を行います
sandbox を設定せずに BrowserWindow を使用する	preload が Node.js に完全にアクセスできます	sandbox を有効にします（Electron 20 以降はデフォルト）
IPC 引数を検証しない	レンダラーからのインジェクション攻撃を受ける可能性があります	Zod または手動チェックで検証します
サーバーを 0.0.0.0 にバインドする	ローカルサーバーがネットワークに公開されます	必ず 127.0.0.1 にバインドします
CSP ヘッダーがない	スクリプトインジェクションの経路になります	HTTP ヘッダーで厳格な CSP を設定します
IPC エラーをシリアライズしない	境界を越えるとエラーのコンテキストが失われます	Result 型パターンを使用します
テストに Spectron を使用する	非推奨で、対応する Electron は最大 13 です	Playwright を使用します

セキュリティ監査チェックリストの全項目については、references/security/security-checklist.md を参照してください。

スクリプトリファレンス

analyze-security.ts

Electron プロジェクトのセキュリティ設定ミスを分析します。

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

安全なデフォルト設定で、新しい Electron + React プロジェクトのひな形を作成します。

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

IPC ハンドラーファイルから TypeScript の型定義を生成します。

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

追加リソース

セキュリティ

• references/security/context-isolation.md - contextBridge と分離のパターン
• references/security/csp-and-permissions.md - コンテンツセキュリティポリシーの設定
• references/security/security-checklist.md - セキュリティ監査チェックリストの全項目

IPC 通信

• references/ipc/typed-ipc.md - 型付きチャネルマップのパターン
• references/ipc/electron-trpc.md - 型安全性を完全に確保するための tRPC 統合
• references/ipc/error-serialization.md - IPC 境界を越える Result 型

アーキテクチャ

• references/architecture/project-structure.md - ディレクトリ構成
• references/architecture/process-separation.md - Main、preload、renderer の役割
• references/architecture/multi-window-state.md - ウィンドウ間での共有状態

React との統合

• references/integration/react-patterns.md - useEffect のクリーンアップ、Strict Mode
• references/integration/state-management.md - Zustand と electron-store のパターン

パッケージ化と配布

• references/packaging/code-signing.md - プラットフォーム別の署名ワークフロー
• references/packaging/auto-updates.md - electron-updater の設定
• references/packaging/bundle-optimization.md - サイズ削減の手法
• references/packaging/ci-cd-patterns.md - GitHub Actions のマトリックスビルド

テスト

• references/testing/playwright-e2e.md - Playwright の Electron サポート
• references/testing/unit-testing.md - Jest/Vitest のマルチプロジェクト設定
• references/testing/test-structure.md - テスト構成のパターン

ツール

• references/tooling/electron-vite.md - ビルドツールの設定
• references/tooling/electron-forge.md - パッケージ化と配布
• references/tooling/tauri-comparison.md - 代わりに Tauri を選ぶ場合

テンプレート

• assets/templates/main-process.ts.md - Main プロセスのスターターテンプレート
• assets/templates/preload-script.ts.md - contextBridge を使用した preload スクリプト
• assets/templates/ipc-handler.ts.md - IPC ハンドラーモジュールのテンプレート
• assets/templates/react-root.tsx.md - React ルートコンポーネントのテンプレート

設定例

• assets/configs/electron-vite.config.ts.md - electron-vite の設定
• assets/configs/forge.config.js.md - Electron Forge の設定
• assets/configs/tsconfig.json.md - TypeScript の設定プリセット
• assets/configs/playwright.config.ts.md - Playwright Electron テストの設定

完全な例

• assets/examples/typed-ipc-example.md - 型付き IPC のエンドツーエンドの解説
• assets/examples/multi-window-example.md - マルチウィンドウの状態管理