---
name: chrome-extension-dev
description: "Chrome/ブラウザ拡張機能開発の包括的ガイド。WXTフレームワーク、Manifest V3、Chrome API、テスト手法をカバー。Use when: ブラウザ拡張機能を作成・修正する時。Triggers on 'ブラウザ拡張機能', 'Chrome拡張', 'browser extension', 'WXT', 'content script', 'service worker'."
argument-hint: "作りたい拡張機能、困っている API、対象ファイル"
user-invocable: true
license: CC BY-NC-SA 4.0
metadata:
  author: yamapan (https://github.com/aktsmm)
---

# Chrome Extension Dev

ブラウザ拡張機能開発の包括的ガイド。

## When to Use

- **ブラウザ拡張機能を作りたい**、**Chrome拡張**、**browser extension**
- WXT フレームワークでの開発
- Content Script / Service Worker の実装
- Chrome API（tabs, storage, cookies等）の使用
- Manifest V3 への対応・移行

## 推奨技術スタック（2025/2026）

| カテゴリ         | 推奨                                 |
| ---------------- | ------------------------------------ |
| フレームワーク   | **WXT** (Vite ベース)                |
| フロントエンド   | React 18+ / Vue 3 / Svelte           |
| 言語             | TypeScript                           |
| スタイリング     | Tailwind CSS                         |
| UIコンポーネント | shadcn/ui / Mantine                  |
| 状態管理         | Zustand / Jotai                      |
| テスト           | Vitest (ユニット) + Playwright (E2E) |

## WXT クイックスタート

```bash
# 新規プロジェクト作成
npm create wxt@latest

# テンプレート指定
npm create wxt@latest -- --template react-ts
npm create wxt@latest -- --template vue-ts

# 開発コマンド
npm run dev    # HMR付き開発サーバー
npm run build  # プロダクションビルド
npm run zip    # ストア提出用パッケージ
```

## プロジェクト構成

```
project/
├── entrypoints/           # 自動検出エントリポイント
│   ├── background.ts      # Service Worker
│   ├── content.ts         # Content Script
│   ├── popup/             # Popup UI
│   │   ├── index.html
│   │   └── main.tsx
│   └── options/           # Options Page
├── components/            # 自動インポートUIコンポーネント
├── utils/                 # 自動インポートユーティリティ
├── public/                # 静的アセット（icon等）
├── wxt.config.ts          # WXT設定
└── package.json
```

## 主要 Chrome API

| API                | 用途               | 権限                   |
| ------------------ | ------------------ | ---------------------- |
| `chrome.tabs`      | タブ操作           | `tabs` / `activeTab`   |
| `chrome.storage`   | データ永続化       | `storage`              |
| `chrome.runtime`   | メッセージング     | なし                   |
| `chrome.scripting` | スクリプト/CSS注入 | `scripting` + host権限 |
| `chrome.cookies`   | Cookie操作         | `cookies` + host権限   |
| `chrome.offscreen` | DOM操作（SW内）    | `offscreen`            |

→ 詳細: [references/chrome-api.md](references/chrome-api.md)

## Manifest V3 制限事項

| 制限               | 対処法                           |
| ------------------ | -------------------------------- |
| 30秒タイムアウト   | `chrome.alarms` でウェイクアップ |
| DOMアクセス不可    | `chrome.offscreen` を使用        |
| 永続化なし         | `chrome.storage.session` を使用  |
| eval()禁止         | 事前にバンドル                   |
| リモートコード禁止 | 全コードをバンドル               |

→ 詳細: [references/manifest-v3.md](references/manifest-v3.md)

## 権限変更時の注意

> **⚠️ 重要**: `permissions`/`host_permissions`変更後は**拡張機能の再読み込みでは不十分**。
> 削除→再インストールが必要。

## Key References

| トピック         | リファレンス                                           |
| ---------------- | ------------------------------------------------------ |
| Chrome API 詳細  | [references/chrome-api.md](references/chrome-api.md)   |
| Manifest V3      | [references/manifest-v3.md](references/manifest-v3.md) |
| テスト           | [references/testing.md](references/testing.md)         |
| 公開             | [references/publishing.md](references/publishing.md)   |
| よくあるパターン | [references/patterns.md](references/patterns.md)       |

## Done Criteria

- [ ] WXT プロジェクト構成が正しい
- [ ] 必要な権限が `wxt.config.ts` に設定されている
- [ ] Manifest V3 制限を考慮した実装
- [ ] 開発モードで動作確認済み
- [ ] ビルドエラーがない

## External Resources

- [WXT 公式](https://wxt.dev)
- [Chrome Extension Docs](https://developer.chrome.com/docs/extensions)
- [Chrome API Reference](https://developer.chrome.com/docs/extensions/reference)