コミュニティ WXT ブラウザ拡張機能ベストプラクティス

WXT ブラウザ拡張機能開発のための包括的なパフォーマンス最適化ガイド。8 つのカテゴリーにわたる 49 のルールを含み、自動リファクタリングとコード生成をガイドするために影響度順に優先順位付けされています。WXT v0.20+ 向けに更新。

適用する場面

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

• 新しい WXT ブラウザ拡張機能コードを記述する場合
• サービスワーカーのバックグラウンドスクリプトを実装する場合
• コンテンツスクリプトを Web ページに注入する場合
• 拡張機能コンテキスト間のメッセージング設定をセットアップする場合
• マニフェストの権限とリソースを設定する場合

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

優先度	カテゴリー	影響度	プレフィックス
1	Service Worker ライフサイクル	CRITICAL	svc-
2	コンテンツスクリプト注入	CRITICAL	inject-
3	メッセージング アーキテクチャ	HIGH	msg-
4	ストレージ パターン	HIGH	store-
5	バンドル最適化	MEDIUM-HIGH	bundle-
6	マニフェスト設定	MEDIUM	manifest-
7	UI パフォーマンス	MEDIUM	ui-
8	TypeScript パターン	LOW-MEDIUM	ts-

クイックリファレンス

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

• svc-register-listeners-synchronously - リスナーを同期的に登録してイベント漏落を防止
• svc-avoid-global-state - メモリ内状態の代わりにストレージを使用
• svc-keep-alive-patterns - 長時間の操作でサービスワーカーを起動状態に保つ
• svc-handle-install-update - インストールおよび更新のライフサイクルイベント処理
• svc-offscreen-documents - DOM 操作にはオフスクリーンドキュメントを使用
• svc-declarative-net-request - ネットワークブロッキングには宣言的ルールを使用

2. コンテンツスクリプト注入 (CRITICAL)

• inject-use-main-function - ランタイムコードを main() 関数内に配置
• inject-choose-correct-world - ISOLATED または MAIN ワールドを適切に選択
• inject-run-at-timing - 適切な runAt タイミングを設定
• inject-use-ctx-invalidated - 更新時のコンテキスト無効化処理
• inject-dynamic-registration - 条件付き注入にはランタイム登録を使用
• inject-all-frames - iframe 処理用に allFrames を設定
• inject-spa-navigation - wxt:locationchange で SPA ナビゲーション処理

3. メッセージング アーキテクチャ (HIGH)

• msg-type-safe-messaging - @webext-core/messaging を使用した型安全なメッセージング
• msg-return-true-for-async - 非同期ハンドラーで true を返す (ネイティブ API)
• msg-use-tabs-sendmessage - コンテンツスクリプトには tabs.sendMessage を使用
• msg-use-ports-for-streams - ストリーミング通信にはポートを使用
• msg-handle-no-receiver - メッセージレシーバーがない場合の処理
• msg-avoid-circular-messages - 循環メッセージループの防止

4. ストレージ パターン (HIGH)

• store-use-define-item - 型安全なアクセスに storage.defineItem を使用
• store-choose-storage-area - 適切なストレージエリアを選択
• store-batch-operations - 関連データを単一の defineItem にグループ化
• store-watch-for-changes - リアクティブ更新に watch() を使用
• store-handle-quota-errors - ストレージクォータエラー処理
• store-versioned-migrations - スキーママイグレーションはバージョニング使用

5. バンドル最適化 (MEDIUM-HIGH)

• bundle-split-entrypoints - エントリーポイント別にコード分割
• bundle-analyze-size - バンドルサイズの分析と監視
• bundle-tree-shake-icons - アイコンライブラリは直接インポートを使用
• bundle-externalize-wasm - WASM を動的ロード
• bundle-minify-content-scripts - コンテンツスクリプトサイズを最小化

6. マニフェスト設定 (MEDIUM)

• manifest-minimal-permissions - 最小限の権限を要求
• manifest-use-optional-permissions - オプション権限を段階的に使用
• manifest-web-accessible-resources - Web アクセス可能なリソースの範囲設定
• manifest-content-security-policy - CSP を正しく設定
• manifest-cross-browser-compatibility - 複数ブラウザー対応

7. UI パフォーマンス (MEDIUM)

• ui-use-shadow-dom - 注入 UI には Shadow DOM を使用
• ui-defer-rendering - ポップアップレンダリングを遅延実行
• ui-cleanup-on-unmount - アンマウント時に UI をクリーンアップ
• ui-sidepanel-persistence - サイドパネル状態を保持
• ui-position-fixed-iframe - 複雑な UI には iframe を使用
• ui-avoid-layout-thrashing - DOM 読み取りと書き込みをバッチ処理

8. TypeScript パターン (LOW-MEDIUM)

• ts-use-imports-module - #imports 仮想モジュールと自動インポートを使用
• ts-use-browser-not-chrome - chrome の代わりに browser 名前空間を使用
• ts-type-entrypoint-options - エントリーポイントオプションを明示的に型付け
• ts-augment-browser-types - 不足している API 用に型を拡張
• ts-strict-null-checks - 厳密な null チェックを有効化
• ts-import-meta-env - ビルド情報に import.meta を使用
• ts-avoid-any - ハンドラーで any 型を回避
• ts-path-aliases - インポート用にパスエイリアスを使用

使い方

各ルールの詳細説明とコード例については、個別の参照ファイルを参照してください：

• Section definitions - カテゴリー構造と影響度レベル
• Rule template - 新しいルール追加用テンプレート

参照ファイル

ファイル	説明
references/_sections.md	カテゴリー定義と順序付け
assets/templates/_template.md	新規ルール用テンプレート
metadata.json	バージョンと参照情報