chrome-extension-wxt

WXT による Chrome 拡張機能の開発

次世代フレームワークの WXT を使用して、Chrome、Firefox、Edge、Safari、およびすべての Chromium ブラウザーに対応するモダンなクロスブラウザー拡張機能を、単一のコードベースで構築できます。

このスキルを使用する場面

次のような場合にこのスキルを使用します。

• 新しい Chrome／ブラウザー拡張機能を作成する
• WXT の開発環境をセットアップする
• 拡張機能の機能（ポップアップ、コンテンツスクリプト、バックグラウンドスクリプト）を構築する
• クロスブラウザー互換性を実装する
• Manifest V3（2025 年時点で必須の標準。V2 は非推奨）を使用する
• React 19、Vue、Svelte、または Solid を拡張機能に統合する

クイックスタートのワークフロー

1. WXT プロジェクトを初期化する

# Create new project with framework of choice
npm create wxt@latest

# Or with specific template
npm create wxt@latest -- --template react-ts
npm create wxt@latest -- --template vue-ts
npm create wxt@latest -- --template svelte-ts

2. プロジェクトの構成

WXT はファイルベースの規約を使用します。

project/
├── entrypoints/              # Auto-discovered entry points
│   ├── background.ts         # Service worker
│   ├── content.ts           # Content script
│   ├── popup.html           # Popup UI
│   └── options.html         # Options page
├── components/              # Auto-imported UI components
├── utils/                   # Auto-imported utilities
├── public/                  # Static assets
│   └── icon/               # Extension icons
├── wxt.config.ts           # Configuration
└── package.json

3. 開発コマンド

npm run dev              # Start dev server with HMR
npm run build           # Production build
npm run zip             # Package for store submission

主なエントリーポイント

WXT は entrypoints/ ディレクトリ内のファイル名によってエントリーポイントを認識します。

バックグラウンドスクリプト（サービスワーカー）

// entrypoints/background.ts
export default defineBackground({
  type: 'module',
  persistent: false,

  main() {
    // Listen for extension events
    browser.action.onClicked.addListener((tab) => {
      console.log('Extension clicked', tab);
    });

    // Handle messages
    browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
      // Handle message
      sendResponse({ success: true });
      return true; // Keep channel open for async
    });
  },
});

コンテンツスクリプト

// entrypoints/content.ts
export default defineContentScript({
  matches: ['*://*.example.com/*'],
  runAt: 'document_end',

  main(ctx) {
    // Content script logic
    console.log('Content script loaded');

    // Create UI
    const ui = createShadowRootUi(ctx, {
      name: 'my-extension-ui',
      position: 'inline',
      anchor: 'body',

      onMount(container) {
        // Mount React/Vue component
        const root = ReactDOM.createRoot(container);
        root.render(<App />);
      },
    });

    ui.mount();
  },
});

ポップアップ UI

// entrypoints/popup/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Extension Popup</title>
</head>
<body>
  <div id="root"></div>
  <script type="module" src="./main.tsx"></script>
</body>
</html>

設定

基本的な wxt.config.ts

import { defineConfig } from 'wxt';

export default defineConfig({
  // Framework integration
  modules: ['@wxt-dev/module-react'],

  // Manifest configuration
  manifest: {
    name: 'My Extension',
    description: 'Extension description',
    permissions: ['storage', 'activeTab'],
    host_permissions: ['*://example.com/*'],
  },

  // Browser target
  browser: 'chrome', // or 'firefox', 'edge', 'safari'
});

よく使われるパターン

型安全なストレージ

// utils/storage.ts
import { storage } from 'wxt/storage';

export const storageHelper = {
  async get<T>(key: string): Promise<T | null> {
    return await storage.getItem<T>(`local:${key}`);
  },

  async set<T>(key: string, value: T): Promise<void> {
    await storage.setItem(`local:${key}`, value);
  },

  watch<T>(key: string, callback: (newValue: T | null) => void) {
    return storage.watch<T>(`local:${key}`, callback);
  },
};

型安全なメッセージング

// utils/messaging.ts
interface Messages {
  'get-data': {
    request: { key: string };
    response: { value: any };
  };
}

export async function sendMessage<K extends keyof Messages>(
  type: K,
  payload: Messages[K]['request']
): Promise<Messages[K]['response']> {
  return await browser.runtime.sendMessage({ type, payload });
}

スクリプトの挿入

// Inject script into page context
import { injectScript } from 'wxt/client';

await injectScript('/injected.js', {
  keepInDom: false,
});

ビルドとデプロイ

本番ビルド

# Build for specific browser
npm run build -- --browser=chrome
npm run build -- --browser=firefox

# Create store-ready ZIP
npm run zip
npm run zip -- --browser=firefox

複数ブラウザー向けビルド

# Build for all browsers
npm run zip:all

出力先：.output/my-extension-{version}-{browser}.zip

モダンな技術スタック（2025 年）

Chrome 拡張機能の構築でよく使われる技術の組み合わせです。

WXT + React + Tailwind + shadcn/ui

2025 年に最も人気のあるスタックです。ユーティリティファーストのスタイリングと、あらかじめ構築されたアクセシブルなコンポーネントを組み合わせています。

npm create wxt@latest -- --template react-ts
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
npx shadcn@latest init

最適な用途： 一貫したデザインシステムを備えたモダンな UI 例： https://github.com/imtiger/wxt-react-shadcn-tailwindcss-chrome-extension

WXT + React + Mantine UI

100 以上のコンポーネントと組み込みのダークモードを備えた、包括的なコンポーネントライブラリです。

npm create wxt@latest -- --template react-ts
npm install @mantine/core @mantine/hooks

最適な用途： 複雑なコンポーネントが必要な、機能豊富な拡張機能 例： https://github.com/ongkay/WXT-Mantine-Tailwind-Browser-Extension

WXT + React + TypeScript（最小構成）

UI ライブラリへの依存なしで独自のデザインを実現する、シンプルなセットアップです。

npm create wxt@latest -- --template react-ts

最適な用途： シンプルな拡張機能、または高度にカスタマイズされたデザイン

高度なトピック

高度なトピックの詳細については、次のリファレンスファイルを参照してください。

• React の統合：React の完全なセットアップ、フック、状態管理、よく使われる UI ライブラリについては、references/react-integration.md を参照してください
• Chrome API：例を含む Chrome 拡張機能 API の包括的なリファレンスについては、references/chrome-api.md を参照してください
• Chrome 140 以降の機能：最新の Chrome 拡張機能 API（sidePanel.getLayout() など）については、references/chrome-140-features.md を参照してください
• WXT API：WXT フレームワーク API の完全なドキュメントについては、references/wxt-api.md を参照してください
• ベストプラクティス：セキュリティ、パフォーマンス、アーキテクチャのパターンについては、references/best-practices.md を参照してください

トラブルシューティング

よくある問題と解決策：

1. モジュールが見つからないエラー：モジュールがインストールされ、正しくインポートされていることを確認してください
2. CSP 違反：manifest の content_security_policy を更新してください
3. ホットリロードが動作しない：ブラウザーのコンソールでエラーを確認してください
4. ストレージが保持されない：storage.local または storage.sync を正しく使用してください

これらの問題を回避するための詳しいガイダンスについては、references/best-practices.md を参照してください。

リソース

公式ドキュメント

• WXT ドキュメント：https://wxt.dev
• Chrome 拡張機能ドキュメント：https://developer.chrome.com/docs/extensions
• Firefox 拡張機能ドキュメント：https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons

同梱リソース

• references/：高度な機能についての詳細なドキュメント

拡張機能の構築に必要に応じて、これらのリソースを使用してください。