moai-framework-electron

Electron 33+ デスクトップ開発

クイックリファレンス

Electron 33+ デスクトップアプリ開発スペシャリストは、ウェブ技術を使用したクロスプラットフォームのデスクトップアプリケーションの構築を可能にします。

自動トリガー：electron.vite.config.ts または electron-builder.yml ファイルで検出された Electron プロジェクト、デスクトップアプリの開発依頼、IPC 通信パターンの実装

主な機能

Electron 33 プラットフォーム：

• 最新のウェブ機能に対応する Chromium 130 レンダリングエンジン
• ネイティブシステムにアクセスできる Node.js 20.18 ランタイム
• メインプロセスでのネイティブ ESM サポート
• GPU アクセラレーションによるグラフィックスに対応する WebGPU API

プロセスアーキテクチャ：

• メインプロセスは、アプリケーションごとに単一のインスタンスとして実行され、Node.js へのフルアクセスを持ちます
• レンダラープロセスは、サンドボックス環境でウェブコンテンツを表示します
• プリロードスクリプトは、公開する API を制御しながらメインプロセスとレンダラープロセスを橋渡しします
• ユーティリティプロセスは、UI をブロックせずにバックグラウンドタスクを処理します

IPC 通信：

• リクエストとレスポンスの通信に型安全な invoke/handle パターンを使用します
• contextBridge API により、レンダラーからメインプロセスの機能へ安全にアクセスできます
• メインプロセスからレンダラーへのプッシュ通知には、イベントベースのメッセージングを使用します

自動更新のサポート：

• GitHub および S3 への公開に対応する electron-updater の統合
• ダウンロードサイズを小さくする差分アップデート
• アップデート通知とインストールの管理

パッケージングの選択肢：

• ビルドツールとプラグインエコシステムを統合した Electron Forge
• 柔軟なマルチプラットフォーム配布に対応する electron-builder

セキュリティ機能：

• プロトタイプ汚染を防ぐ contextIsolation
• レンダラープロセスを分離するサンドボックスの適用
• コンテンツセキュリティポリシーの設定
• IPC ハンドラー向けの入力検証パターン

プロジェクトの初期化

新しい Electron アプリケーションを作成するには、vite-typescript テンプレートを指定して create-electron-app コマンドを実行します。パッケージング用に electron-builder を開発依存関係としてインストールします。自動更新機能用に electron-updater をランタイム依存関係として追加します。

詳細なコマンドと設定については、reference.md の Quick Commands セクションを参照してください。

---

実装ガイド

プロジェクト構成

推奨ディレクトリ構成：

ソースディレクトリには、次の 4 つの主要なサブディレクトリを配置します。

Main ディレクトリ：メインプロセスのエントリーポイント、ドメインごとに整理された IPC ハンドラーの定義、ビジネスロジックサービス、ウィンドウ管理モジュールを含みます

Preload ディレクトリ：プリロードスクリプトのエントリーポイントと、メインプロセスとレンダラープロセスを橋渡しする公開 API の定義を含みます

Renderer ディレクトリ：HTML エントリーポイントと Vite の設定を含む、React、Vue、または Svelte で構築されたウェブアプリケーションを含みます

Shared ディレクトリ：メインプロセスとレンダラープロセス間で共有する TypeScript の型と定数を含みます

プロジェクトルートには、ビルド設定用の electron.vite.config.ts、パッケージングオプション用の electron-builder.yml、アプリアイコンとアセット用の resources ディレクトリを配置します。

メインプロセスのセットアップ

アプリケーションのライフサイクル管理：

メインプロセスの初期化は、特定の順序で行います。まず、app.enableSandbox() を使用してサンドボックスをグローバルに有効にし、すべてのレンダラープロセスが分離された環境で実行されるようにします。次に、複数のアプリインスタンスが同時に実行されないよう、シングルインスタンスロックを要求します。

ウィンドウは、アプリの準備完了イベントが発生した後に作成します。BrowserWindow には、contextIsolation の有効化、nodeIntegration の無効化、sandbox の有効化、webSecurity の有効化など、セキュリティを重視した webPreferences を設定します。レンダラーに安全な API を公開するため、preload スクリプトのパスを設定します。

プラットフォーム固有の動作にも対応します。macOS では、ウィンドウが存在しない状態で Dock アイコンがクリックされた場合に、ウィンドウを再作成します。それ以外のプラットフォームでは、すべてのウィンドウが閉じられたときにアプリケーションを終了します。

実装例については、examples.md の Main Process Entry Point セクションを参照してください。

型安全な IPC 通信

IPC 型定義パターン：

チャネル名とペイロード型を対応付けるインターフェースを定義します。ファイル操作、ウィンドウ操作、ストレージ操作など、ドメインごとにチャネルをグループ化します。これにより、メインプロセスのハンドラーとレンダラーからの呼び出しの両方で型チェックが可能になります。

メインプロセスのハンドラー登録：

共有型をインポートする専用モジュールに IPC ハンドラーを登録します。各ハンドラーは、処理の前に Zod などのスキーマ検証ライブラリを使用して入力を検証します。リクエスト／レスポンスパターンには ipcMain.handle を使用し、構造化された結果を返します。

プリロードスクリプトの実装：

各チャネルの ipcRenderer.invoke 呼び出しをラップする API オブジェクトを作成します。contextBridge.exposeInMainWorld を使用して、この API をレンダラーの window.electronAPI として利用できるようにします。メモリーリークを防ぐため、イベントリスナーのクリーンアップ関数を含めます。

IPC の実装パターンの詳細については、examples.md の「型安全な IPC の実装」セクションを参照してください。

セキュリティのベストプラクティス

必須のセキュリティ設定：

すべての BrowserWindow で、webPreferences に4つの重要な設定を行う必要があります。レンダラーコードが Electron の内部機能にアクセスできないよう、contextIsolation は常に有効にします。レンダラープロセスでは nodeIntegration を常に無効にします。プロセスレベルの分離のため、sandbox は常に有効にします。同一オリジンポリシーの適用を維持するため、webSecurity は決して無効にしないでください。

コンテンツセキュリティポリシー：

webRequest.onHeadersReceived を使用して、セッションレベルの CSP ヘッダーを設定します。default-src は self に制限し、script-src は unsafe-inline を使わずに self に制限し、connect-src は許可された API ドメインに制限します。これにより、XSS 攻撃や許可されていないリソースの読み込みを防止できます。

入力検証：

すべての IPC ハンドラーで、処理の前に入力を検証する必要があります。親ディレクトリへの参照を含むパスを拒否し、パストラバーサル攻撃を防ぎます。予約文字に照らしてファイル名を検証します。ファイルアクセスを実装する際は、許可するディレクトリの許可リストを使用します。

セキュリティの実装の詳細については、reference.md の「セキュリティのベストプラクティス」セクションを参照してください。

自動更新の実装

更新サービスのアーキテクチャ：

electron-updater のライフサイクルを管理する UpdateService クラスを作成します。UI 通知を可能にするため、メインウィンドウの参照を渡して初期化します。帯域幅の使用をユーザーが制御できるよう、autoDownload を false に設定します。

イベント処理：

update-available イベントを処理してレンダラーに通知し、ダウンロードの確認をユーザーに促します。download-progress イベントを追跡し、進行状況インジケーターを表示します。update-downloaded イベントを処理し、再起動を促します。

ユーザーへの通知パターン：

更新が利用可能になったときとダウンロードが完了したときに、システムダイアログを使用してユーザーに通知します。アプリ内通知の表示に使用するイベントをレンダラーに送信します。即時インストールと後で行うインストールの両方に対応します。

更新サービスの実装例については、examples.md の「自動更新の統合」セクションを参照してください。

アプリのパッケージ化

Electron Builder の設定：

プラットフォーム登録用に、逆ドメイン形式で appId を設定します。システム UI に表示する productName を指定します。macOS、Windows、Linux 向けにプラットフォーム固有のターゲットを設定します。

macOS の設定：

App Store の分類用に category を設定します。notarization のために hardenedRuntime を有効にし、entitlements を設定します。x64 と arm64 の両方のアーキテクチャを対象とするユニバーサルビルドを設定します。

Windows の設定：

実行ファイルとインストーラーのアイコンパスを指定します。インストール先ディレクトリの選択など、NSIS インストーラーのオプションを設定します。適切なハッシュアルゴリズムを使用して、コード署名を設定します。

Linux の設定：

デスクトップ環境との統合用に category を設定します。ユニバーサルな配布に使用する AppImage と、パッケージマネージャーでのインストールに使用する deb/rpm など、複数のターゲットを設定します。

設定例の詳細については、reference.md の「設定」セクションを参照してください。

---

高度なパターン

高度なトピックの詳細なドキュメントについては、reference.md と examples.md をご覧ください。

ウィンドウ状態の永続化：

• セッションをまたいでウィンドウの位置とサイズを保存、復元する
• 複数のディスプレイやディスプレイの変更に対応する
• 最大化状態と全画面状態を管理する

複数ウィンドウの管理：

• 適切な親子関係を持つセカンダリウィンドウを作成する
• 複数のウィンドウ間で状態を共有する
• ウィンドウのライフサイクルイベントを調整する

システムトレイとネイティブメニュー：

• コンテキストメニュー付きのシステムトレイアイコンを作成、更新する
• キーボードショートカット付きのアプリケーションメニューを構築する
• macOS と Windows 向けのプラットフォーム固有のメニューパターンを使用する

ユーティリティプロセス：

• CPU 負荷の高いバックグラウンドタスク用にユーティリティプロセスを起動する
• MessageChannel を介してユーティリティプロセスと通信する
• ユーティリティプロセスのライフサイクルとエラー処理を管理する

ネイティブモジュールの統合：

• Electron の Node.js バージョンに合わせてネイティブモジュールを再ビルドする
• ローカルデータベースの保存に better-sqlite3 を使用する
• 安全な認証情報の保存に keytar を統合する

プロトコルハンドラーとディープリンク：

• アプリの起動用にカスタム URL プロトコルを登録する
• 異なるプラットフォームでディープリンクを処理する
• カスタムプロトコルを介して OAuth コールバックを処理する

パフォーマンスの最適化：

• ウィンドウや負荷の高いモジュールを遅延読み込みする
• 初期化を遅らせて起動時間を最適化する
• 長時間実行されるアプリケーションのメモリを管理する

---

相性の良い項目

• .claude/rules/moai/languages/typescript.md - 型安全な Electron 開発のための TypeScript パターン（paths frontmatter により自動読み込み）
• moai-domain-frontend - React、Vue、または Svelte によるレンダラー開発
• .claude/rules/moai/languages/javascript.md - メインプロセス向けの Node.js パターン（paths frontmatter により自動読み込み）
• moai-domain-backend - バックエンド API の統合
• moai-workflow-testing - デスクトップアプリのテスト戦略

---

トラブルシューティング

よくある問題と解決策：

起動時に画面が白くなる：

ビルド済み出力ディレクトリを基準に、プリロードスクリプトのパスが正しく設定されていることを確認してください。loadFile または loadURL のパスが既存のファイルを指していることを確認してください。devTools を有効にして、コンソールエラーを調べてください。スクリプトの実行を妨げている可能性がある CSP 設定を確認してください。

IPC が動作しない：

メインチャンネルハンドラーとレンダラーからの呼び出しで、チャンネル名が完全に一致していることを確認してください。ウィンドウがコンテンツを読み込む前にハンドラーが登録されていることを確認してください。contextBridge の使用が exposeInMainWorld を使った正しいパターンに従っていることを確認してください。

ネイティブモジュールが動作しない：

npm install の後に electron-rebuild を実行し、ネイティブモジュールを再コンパイルしてください。Electron に組み込まれている Node.js のバージョンと一致させてください。再ビルドを自動化するため、postinstall スクリプトを追加してください。

自動更新が動作しない：

更新には署名が必要なため、アプリケーションがコード署名されていることを確認してください。electron-builder.yml の公開設定を確認してください。接続の問題を診断するため、electron-updater のログ記録を有効にしてください。更新チェックを妨げている可能性があるファイアウォール設定を確認してください。

デバッグコマンド：

npx electron-rebuild でネイティブモジュールを再ビルドします。npx electron --version で Electron のバージョンを確認します。DEBUG=electron-updater 環境変数で詳細な更新ログを有効にします。

---

リソース

完全なコード例と設定テンプレートについては、以下をご覧ください。

• reference.md - 詳細な API ドキュメント、バージョンマトリックス、Context7 ライブラリマッピング
• examples.md - すべてのパターンを網羅した本番環境対応のコード例

最新のドキュメントについては、Context7 で以下を照会してください。

• /electron/electron は Electron のコア API 用
• /electron/forge は Electron Forge ツール用
• /electron-userland/electron-builder はパッケージ設定用

---

バージョン：2.0.0 最終更新日：2026-01-10 変更点：CLAUDE.md のドキュメント標準に準拠するために再構成し、すべてのコード例を削除して説明文形式に変更しました

よくある合理化

合理化	実際のところ
「レンダラープロセスで Node.js API を直接使えます」	レンダラープロセスは信頼できないコンテンツを実行します。Node.js に直接アクセスできると、リモートコード実行の経路になります。プリロードブリッジを介した IPC を使用してください。
「自分のコードは信頼しているので、contextIsolation は不要です」	コンテキスト分離により、Web コンテンツからのプロトタイプ汚染が Node.js に到達するのを防ぎます。これはコードを信頼するかどうかではなく、コンテキストを分離するためのものです。
「自動更新はリリース後に設定できます」	自動更新なしでリリースすると、ユーザーは脆弱なバージョンを使い続けることになります。初回リリース前に設定してください。
「アプリのパッケージ化は後で行います。テストには開発ビルドで十分です」	開発ビルドでは、ファイルパス、権限、コード署名が異なります。実際の配布上の問題が明らかになるのは、本番用にパッケージ化したビルドだけです。
「IPC は遅いので、グローバル変数で状態を共有します」	IPC のオーバーヘッドはマイクロ秒単位です。グローバル変数は、セキュリティのために設けられたプロセス分離を迂回します。

危険信号

• BrowserWindow オプションで nodeIntegration が true に設定されている
• セキュリティ上の根拠が文書化されていないのに contextIsolation が false に設定されている
• レンダラープロセスが electron または node モジュールから直接インポートしている（プリロードを迂回）
• 自動更新の仕組みが設定されていない
• IPC ハンドラーがレンダラーからの引数を検証またはサニタイズしていない

検証

• すべての BrowserWindow で nodeIntegration が false、contextIsolation が true に設定されている
• レンダラーからメインへの通信はすべて contextBridge と IPC を使用している
• IPC ハンドラーが処理前に入力引数を検証している
• 自動更新が設定され、テスト済みである（更新設定を提示）
• Electron Forge でアプリを正常にパッケージ化できる（ビルド出力を提示）
• レンダラープロセスのコードに require('electron') が直接記述されていない

テレメトリー期間

ステータス：不明（60 日間） R4 監査判定：維持（監視） SPEC：SPEC-V3R2-WF-001 §6.2 (REQ-WF001-013) 期間開始：2026-04-25（Wave 1.5 のコミット日） 期間終了：2026-06-24（60 日間） 再監査のトリガー：このスキルの SessionStart フックの起動回数 判断基準：

• 期間中の起動回数が 5 回以上 → 恒久的に維持
• 期間中の起動回数が 0 回 → v3.1 で RETIRE を予定
• 0 < 起動回数 < 5 → 「low-use」タグを付けて維持