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

セキュアで本番環境対応のElectronアプリケーションをReactで構築するようAIエージェントをガイドします。このスキルはセキュリティパターン、タイプセーフなIPC通信、プロジェクトセットアップガイダンス、パッケージング・コード署名ワークフロー、および分析・スキャフォーリング・型生成用のツールを提供します。

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

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

• Electron main、preload、または renderer プロセスコード生成時
• electron-vite または Electron Forge 設定時
• プロセス間のIPC通信セットアップ時
• セキュリティパターンの実装時（contextBridge、sandbox、CSP）
• デスクトップアプリケーションのパッケージング・署名・公証時
• Playwright を使用した Electron アプリテスト時
• マルチウィンドウアーキテクチャ設計時

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

• Tauri アプリ構築時（異なるパラダイム、Tauri固有のガイダンス使用）
• デスクトップ要件のない純粋なウェブアプリ構築時
• Electron 20以下をターゲットとする場合（セキュリティデフォルトが異なる）
• React以外のrendererフレームワーク使用時（フレームワーク固有のスキル使用）

コア原則

1. セキュリティファースト アーキテクチャ

モダンなElectronセキュリティはElectron 20以降で標準化された3つのデフォルトに依存しています：コンテキスト分離、サンドボックスモード、nodeIntegration無効化。これらのいずれかを無効化するとXSS攻撃が完全なリモートコード実行にエスカレートする可能性があります。すべてのmain-renderer通信はcontextBridgeを通じてフローします：

// preload.ts - SECURE パターン
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);
  }
});

ローカルファイル読み込みアプリケーション用のContent Security PolicyをHTTPヘッダー経由で設定し、スクリプトソースを'self'に制限します。

2. タイプセーフなIPC通信

invoke/handleパターンは、リクエスト-レスポンス通信において send/on より推奨されます。適切な非同期/待機セマンティクスとエラー伝播を提供します。型付きチャネルの場合、マップ型パターンを使用します：

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

複雑なアプリケーション向けに、electron-trpc は tRPC のルーターパターンを使用したZod検証による完全な型安全性を提供します：

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

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

3. モダンプロジェクトセットアップ

推奨スタックは、開発用にelectron-viteを、パッケージング用にElectron Forgeを使用します。electron-viteは、main、preload、renderプロセスを管理する統一設定を提供し、開発サーバーの起動が1秒以下、HMRがインスタント化されます。Electron Forgeは署名と公証にファーストパーティのElectronパッケージを使用します。

src/
├── main/           # Main プロセス (Node.js 環境)
│   ├── index.ts
│   └── ipc/        # IPC ハンドラー
├── preload/        # contextBridge を通じたセキュアブリッジ
│   ├── index.ts
│   └── index.d.ts  # 公開API用のTypeScript宣言
└── renderer/       # React アプリケーション (純粋なウェブ、Node アクセスなし)
    ├── src/
    └── index.html

4. React 統合パターン

React 18の並行機能はElectronのChromiumベースrendererで通常通り動作します。Strict Modeのエフェクトの二重呼び出しはメモリ問題につながるIPC リスナーリークをキャッチします。IPC リスナーを登録するエフェクトから常にクリーンアップ関数を返します：

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

マルチウィンドウアプリケーションの場合、mainプロセスが共有状態の単一の真実のソースとして機能すべきです。electron-storeとの永続化の組み合わせでIPC ブロードキャストを使用して、任意のウィンドウのミューテーションがすべてのウィンドウを更新するようにします。

クイックリファレンス

カテゴリー	推奨	回避
セキュリティ	contextBridge.exposeInMainWorld()	nodeIntegration: true
IPC	invoke/handle パターン	リクエスト-レスポンスの send/on
Preload	型付き関数ラッパー	生の 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
マルチウィンドウ	状態ハブとしてのmainプロセス	ウィンドウ間直接通信

コード生成ガイドライン

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

関連するハンドラーをモジュールにグループ化します。すべての戻り値に結果型パターンを使用します。rendererプロセスから受け取るすべての引数を検証します。

一般的なアンチパターン

Electronコードを生成する場合、これらのパターンを回避します：

アンチパターン	問題点	解決策
nodeIntegration: true	XSSが完全なRCEにエスカレート	無効化を維持（デフォルト）
ipcRendererの直接公開	rendererからの完全なIPCアクセス	contextBridgeの関数でラップ
contextIsolationなし	rendererがpreloadスコープにアクセス	有効化を維持（Electron 12以降デフォルト）
コード署名なし	OSセキュリティ警告、Gatekeeperブロック	すべてのプラットフォーム向けに署名・公証
sandboxなしのBrowserWindow	preloadが完全なNode.jsアクセス	sandboxを有効化（Electron 20以降デフォルト）
未検証のIPC引数	rendererからのインジェクション攻撃	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    すべてのチェックを有効化
  --json      CIの為JSONで出力
  -h, --help  ヘルプを表示

Examples:
  # プロジェクトの分析
  deno run --allow-read scripts/analyze-security.ts ./src

  # CI パイプライン用 Strict モード
  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>     アプリケーション名（必須）
  --path <path>     ターゲットディレクトリ（デフォルト：./）
  --with-react      React セットアップを含める
  --with-trpc       electron-trpc を含める
  --with-tests      Playwright テストを含める

Examples:
  # React を使用した基本的なアプリケーション
  deno run --allow-read --allow-write scripts/scaffold-electron-app.ts \
    --name "my-app" --with-react

  # trpc とテストを使用した完全なセットアップ
  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>  IPC ハンドラーファイルへのパス
  --output <path>    型定義の出力パス
  --validate         既存の型がハンドラーと一致することを検証

Examples:
  # ハンドラーから型を生成
  deno run --allow-read --allow-write scripts/generate-ipc-types.ts \
    --handlers ./src/main/ipc --output ./src/preload/ipc-types.d.ts

  # 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 - Content Security Policy 設定
• 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 - マルチウィンドウ状態管理