chrome-ext

Chrome Developer Relations Chrome 拡張機能のベストプラクティス

Chrome Developer Relations がメンテナンスする、Chrome 拡張機能（Manifest V3）の包括的なパフォーマンス最適化ガイドです。自動リファクタリングとコード生成の指針となるよう、影響度の高い順に優先順位を付けた 8 つのカテゴリに、40 以上のルールを掲載しています。

適用する場面

次のような場合に、これらのガイドラインを参照してください。

• Chrome 拡張機能のコードを新たに記述するとき
• Manifest V2 から Manifest V3 に移行するとき
• サービスワーカーのライフサイクルと状態管理を最適化するとき
• ページとやり取りするコンテンツスクリプトを実装するとき
• 拡張機能のパフォーマンス問題をデバッグするとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	サービスワーカーのライフサイクル	重大	sw-
2	コンテンツスクリプトの最適化	重大	content-
3	メッセージパッシングの効率化	高	msg-
4	ストレージ操作	高	storage-
5	ネットワークと権限	中〜高	net-
6	メモリ管理	中	mem-
7	UI パフォーマンス	中	ui-
8	API の使用パターン	低〜中	api-

クイックリファレンス

1. サービスワーカーのライフサイクル（重大）

• sw-persist-state-storage - グローバル変数ではなく chrome.storage を使って状態を永続化します
• sw-avoid-keepalive - 人為的なサービスワーカーのキープアライブパターンを避けます
• sw-use-alarms-api - setTimeout/setInterval ではなく chrome.alarms を使います
• sw-return-true-async - 非同期レスポンスを返す場合、メッセージリスナーから true を返します
• sw-register-listeners-toplevel - イベントリスナーをトップレベルで登録します
• sw-use-offscreen-for-dom - DOM API にはオフスクリーンドキュメントを使います

2. コンテンツスクリプトの最適化（重大）

• content-use-specific-matches - 具体的な URL マッチパターンを使います
• content-use-document-idle - コンテンツスクリプトの挿入には document_idle を使います
• content-programmatic-injection - マニフェストでの宣言より、プログラムによる挿入を優先します
• content-minimize-script-size - コンテンツスクリプトのバンドルサイズを最小限に抑えます
• content-batch-dom-operations - リフローを最小限にするため、DOM 操作をまとめて実行します
• content-use-mutation-observer - ポーリングではなく MutationObserver を使います

3. メッセージパッシングの効率化（高）

• msg-use-ports-for-frequent - 頻繁にメッセージをやり取りする場合はポート接続を使います
• msg-minimize-payload-size - メッセージのペイロードサイズを最小限に抑えます
• msg-debounce-frequent-events - 高頻度イベントは、メッセージ送信前にデバウンスします
• msg-check-lasterror - 必ず chrome.runtime.lastError を確認します
• msg-avoid-broadcast-to-all-tabs - すべてのタブへのメッセージのブロードキャストを避けます

4. ストレージ操作（高）

• storage-batch-operations - ストレージ操作は個別に呼び出すのではなく、まとめて実行します
• storage-choose-correct-type - ユースケースに合ったストレージの種類を選びます
• storage-cache-frequently-accessed - 頻繁にアクセスするストレージ値をキャッシュします
• storage-use-session-for-temp - 一時的なランタイムデータには storage.session を使います
• storage-avoid-storing-large-blobs - 大きなバイナリデータの保存を避けます

5. ネットワークと権限（中〜高）

• net-use-declarativenetrequest - webRequest の代わりに declarativeNetRequest を使用します
• net-request-minimal-permissions - 必要最小限の権限を要求します
• net-use-activetab - 広範なホスト権限の代わりに activeTab 権限を使用します
• net-limit-csp-modifications - Content Security Policy ヘッダーの変更を避けます

6. メモリ管理（中）

• mem-cleanup-event-listeners - コンテンツスクリプトのアンロード時にイベントリスナーをクリーンアップします
• mem-avoid-detached-dom - デタッチされた DOM ノードへの参照を保持しないようにします
• mem-avoid-closure-leaks - クロージャによる意図しないメモリリークを避けます
• mem-clear-intervals-timeouts - クリーンアップ時にインターバルとタイムアウトをクリアします
• mem-use-weak-collections - DOM 要素への参照には WeakMap と WeakSet を使用します

7. UI パフォーマンス（中）

• ui-minimize-popup-bundle - 起動を高速化するため、ポップアップのバンドルサイズを最小限にします
• ui-render-with-cached-data - まずキャッシュされたデータでポップアップ UI を描画します
• ui-batch-badge-updates - バッジのちらつきを防ぐため、更新をまとめて処理します
• ui-use-options-page-lazy - オプションページのセクションを遅延読み込みします

8. API の使用パターン（低〜中）

• api-use-promises-over-callbacks - コールバックよりも Promise ベースの API 呼び出しを使用します
• api-query-tabs-efficiently - 特定のフィルターを指定してタブを照会します
• api-avoid-redundant-api-calls - ループ内での冗長な API 呼び出しを避けます
• api-use-alarms-minperiod - alarms API の最小間隔を守ります
• api-handle-context-invalidated - 拡張機能のコンテキストが無効化されたエラーに対処します
• api-use-declarative-content - ページアクションには declarative content API を使用します

使用方法

詳しい説明とコード例については、個別のリファレンスファイルをお読みください。

• セクション定義 - カテゴリーの構成と影響レベル
• ルールテンプレート - 新しいルールを追加するためのテンプレート

完全版ドキュメント

すべてのルールを1つのドキュメントにまとめた完全なガイドについては、AGENTS.md をご覧ください。

リファレンスファイル

ファイル	説明
AGENTS.md	すべてのルールをまとめた完全なガイド
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報