Chrome Extension ベストプラクティス

Chrome Extensions (Manifest V3) の包括的なパフォーマンスとコード品質ガイド。12カテゴリーで67個のルールを含み、自動リファクタリングとコード生成をガイドするために影響度で優先順位付けされています。

適用する場合

以下の場合にこれらのガイドラインを参照してください:

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

ルールカテゴリー優先度順

優先度	カテゴリー	影響	プリフィックス
1	Service Worker ライフサイクル	CRITICAL	sw-
2	Content Script 最適化	CRITICAL	content-
3	メッセージパッシング効率	HIGH	msg-
4	ストレージ操作	HIGH	storage-
5	ネットワーク・パーミッション	MEDIUM-HIGH	net-
6	メモリ管理	MEDIUM	mem-
7	UI パフォーマンス	MEDIUM	ui-
8	API 使用パターン	LOW-MEDIUM	api-
9	コードスタイル・命名	MEDIUM	style-
10	コンポーネントパターン	MEDIUM	comp-
11	エラーハンドリング	HIGH	err-
12	テストパターン	MEDIUM	test-

クイックリファレンス

1. Service Worker ライフサイクル (CRITICAL)

• 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 Script 最適化 (CRITICAL)

• 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. メッセージパッシング効率 (HIGH)

• 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. ストレージ操作 (HIGH)

• storage-batch-operations - 個別の呼び出しの代わりにストレージ操作をバッチ処理する
• storage-choose-correct-type - ユースケースに合った正しいストレージタイプを選択する
• storage-cache-frequently-accessed - 頻繁にアクセスされるストレージ値をキャッシュする
• storage-use-session-for-temp - 一時的なランタイムデータにstorage.sessionを使用する
• storage-avoid-storing-large-blobs - 大きなバイナリBLOBの保存を避ける

5. ネットワーク・パーミッション (MEDIUM-HIGH)

• net-use-declarativenetrequest - webRequestの代わりにdeclarativeNetRequestを使用する
• net-request-minimal-permissions - 必要最小限のパーミッションをリクエストする
• net-use-activetab - 広範なホストパーミッションの代わりにactiveTabパーミッションを使用する
• net-limit-csp-modifications - Content Security Policyヘッダーの変更を避ける

6. メモリ管理 (MEDIUM)

• 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 パフォーマンス (MEDIUM)

• ui-minimize-popup-bundle - ポップアップバンドルサイズを最小化して高速起動する
• ui-render-with-cached-data - キャッシュデータでポップアップUIをまず レンダリングする
• ui-batch-badge-updates - ちらつきを避けるためバッジ更新をバッチ処理する
• ui-use-options-page-lazy - オプションページセクションを遅延ロードする

8. API 使用パターン (LOW-MEDIUM)

• api-use-promises-over-callbacks - コールバックの代わりにPromiseベースのAPI呼び出しを使用する
• api-query-tabs-efficiently - 特定のフィルターでタブをクエリする
• api-avoid-redundant-api-calls - ループ内の冗長なAPI呼び出しを避ける
• api-use-alarms-minperiod - alarmsAPI最小期間を守る
• api-handle-context-invalidated - 拡張機能コンテキスト無効化エラーを処理する
• api-use-declarative-content - ページアクションに宣言型コンテンツAPIを使用する

9. コードスタイル・命名 (MEDIUM)

• style-boolean-naming - ブール変数にis/has/shouldプリフィックスを使用する
• style-cache-naming - 一貫したキャッシュ変数命名を使用する
• style-constants - マジック値に定数を定義する
• style-directory-structure - コードを機能/レイヤーで整理する
• style-file-naming - 一貫したファイル命名規則を使用する
• style-function-naming - 説明的な関数名を使用する
• style-import-type - 型にtype-only importsを使用する
• style-index-entry-points - モジュールエントリーポイントにindexファイルを使用する
• style-message-enums - メッセージタイプにenumを使用する
• style-type-naming - 型とインターフェースにPascalCaseを使用する

10. コンポーネントパターン (MEDIUM)

• comp-adapter-interface - ブラウザAPIのアダプターパターンを使用する
• comp-content-script-structure - コンテンツスクリプトを一貫して構成する
• comp-css-class-patterns - BEMまたはプリフィックス付きCSSクラスを使用する
• comp-manager-class - 複雑な状態にはマネージャークラスを使用する
• comp-type-guards - ランタイム検証に型ガードを使用する
• comp-ui-components - 再利用可能なUIコンポーネントを作成する

11. エラーハンドリング (HIGH)

• err-context-invalidation - 拡張機能コンテキスト無効化を処理する
• err-early-return - エラーハンドリングに早期returnを使用する
• err-null-coalescing - デフォルト値にnullish coalescingを使用する
• err-promise-barrier - 調整にPromiseバリアを使用する
• err-storage-operations - ストレージ操作の失敗を処理する
• err-url-parsing - try/catchでURLを安全にパースする
• err-validation-pattern - 境界で入力を検証する

12. テストパターン (MEDIUM)

• test-browser-api-mocking - テスト内でchrome APIをモックする
• test-organization - テストを機能で整理する
• test-validation-functions - 検証関数を徹底的にテストする

使用方法

詳細な説明とコード例については、個別のリファレンスファイルを読んでください:

• セクション定義 - カテゴリー構造と影響レベル
• ルールテンプレート - 新しいルール追加用テンプレート

完全なコンパイル済みドキュメント

すべてのルールを含む完全ガイドを1つのドキュメントで見るには、AGENTS.mdを参照してください。

リファレンスファイル

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