🔨

Vite + TypeScript で作る Chrome 拡張(MV3) Step1

に公開
2025/08/28

Vite + TypeScript で作る Chrome 拡張(MV3)

今回はプロローグ的なものとハンズオン Step1「Vite + TypeScript + MV3 の最小スケルトンを作る」をお届けします。

概要

本記事は「Vite + TypeScript で作る Chrome 拡張(MV3)」のハンズオンです。
Chrome 拡張の基礎的な知識も載せていきます。

想定読者

  • Chrome 拡張機能を作りたい人。
  • TypeScript の最低限の基礎知識がある人

HOW

なぜ TypeScript を使うのか

以下個人的な感想になりますが、
型安全でエラーの検知に優れ、実行前にバグを潰せるから。JavaScript 時代では当たり前のように頻出していた実行時エラーがほぼ0になりました。
あとは型情報による強力な補完・ナビゲーションで生産性が爆増します。

なぜ Vite を使うのか

importを使うと以下のエラーが発生するからです。

Uncaught SyntaxError: Cannot use import statement outside a module

これは拡張の content scripts は既定で「通常のスクリプト(classic)」として読み込まれ、「モジュール」としては読み込まれないためです。
そのためこれは構文エラーになります。公式ドキュメントでも content scripts に type: "module" を指定する方法は記されていません。
この対処方法として今回は Vite で依存モジュールをまとめて 1 ファイルの js を出力する(実行時 import を残さない)方法を取ります。

ハンズオン

Step1: Vite + TypeScript + MV3 の最小スケルトンを作る

1. プロジェクト作成 & 依存追加

# 任意の作業ディレクトリで(--template vanilla-ts: フレームワーク無し + TypeScript(Vanilla TS)の構成)
npm create vite@latest [生成先のディレクトリ名] -- --template vanilla-ts
cd chrome-ext-ts

# 拡張向けViteプラグインと型
npm i -D @crxjs/vite-plugin @types/chrome

# 不要なファイルを削除(vite-env.d.tsは任意。このハンズオンでは使いません。)
rm -f index.html src/main.ts src/counter.ts src/style.css src/typescript.svg src/vite-env.d.ts

2. Manifest(MV3)作成

manifest.jsonをsrc/に作成

{
  "manifest_version": 3,
  "name": "Vite TS MV3 Starter",
  "version": "0.0.1",
  "action": { "default_popup": "src/popup.html" },
  "background": { "service_worker": "src/background.ts", "type": "module" },
  "options_page": "src/options.html",
  "content_scripts": [
    {
      "matches": ["<all_urls>"],
      "js": ["src/content.ts"],
      "run_at": "document_idle"
    }
  ],
  "permissions": ["storage", "activeTab", "scripting"]
}
項目 説明
manifest_version 拡張のマニフェスト仕様のバージョン。MV3 を使う宣言。ここは常に 3
name ストアや拡張一覧に表示される名称。後で _locales/ を用意すれば多言語化も可。
version 拡張の版数。1〜4 個の整数をドットで区切る(例: 0.0.1)。ストア提出時はここを上げる必要あり。
action ツールバーの拡張アイコンをクリックしたときに開く HTML。未指定だとクリックしても何も開かない。(default_popup)
他に default_title や default_icon の設定可。
background 拡張のバックグラウンド処理(Service Worker)。type: "module" により ESM の import が使える。DOM は無い世界なので window や document は使えない。イベント駆動(onInstalled 等)で動き、アイドルで停止することがある前提で設計。
options_page 設定ページとして表示する HTML。拡張の詳細画面や chrome.runtime.openOptionsPage() から開ける。
※ MV3 では options_ui: { "page": "...", "open_in_tab": true } も使える(挙動はほぼ同じ)。
content_scripts content script は “classic script” として実行されるため、ファイル内で直接 import は不可(バンドルで依存を 1 ファイル化して解決するのが定石)。ページ側の JS とは世界が分離(isolated world)しているので、直接の変数共有はできず、必要なら postMessage 等で橋渡し。
> matches 自動注入する対象ページの URL パターン。"<all_urls>" は全ページ対象だが、公開時は最小権限の観点で絞るのが望ましい。
> js 注入するスクリプト。CRXJS がビルド後のパスへ差し替える。
> run_at いつ実行するか(document_start / document_end / document_idle)。未指定時の既定は document_idle。
permissions
> storage chrome.storage が使える(設定保存など)。
> activeTab ユーザーの操作(クリック等)をトリガーに、その時アクティブなタブに限って一時的なホスト権限を得る。
> scripting chrome.scripting.executeScript/insertCSS でプログラム的にスクリプト/CSS を注入するための権限。対象サイトに対しては host_permissions か activeTab のどちらかで権限を満たす必要あり。

3. Vite 設定

vite.config.tsをプロジェクト直下(ルート)に作成

import { defineConfig } from "vite";
import { crx } from "@crxjs/vite-plugin";
import manifest from "./src/manifest.json";

export default defineConfig({
  plugins: [crx({ manifest })],
  build: { outDir: "dist", sourcemap: true },
  esbuild: { target: "chrome114" },
});

4. エントリ群を追加

下記ファイルを作成。

src/background.ts

chrome.runtime.onInstalled.addListener(
  (details: chrome.runtime.InstalledDetails) => {
    console.log("[ext] onInstalled:", details.reason);
  }
);

src/content.ts

((): void => {
  console.log("[ext] content loaded on:", location.href);
})();

src/popup.html

<!DOCTYPE html>
<html lang="en">
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width,initial-scale=1" />
  <title>Popup</title>
  <body>
    <div id="app">Popup is working 🎉</div>
    <script type="module" src="./popup.ts"></script>
  </body>
</html>

src/popup.ts

const el = document.getElementById("app") as HTMLDivElement;
el.textContent = "Popup is working 🎉 (TypeScript)";

src/options.html

<!DOCTYPE html>
<html lang="en">
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width,initial-scale=1" />
  <title>Options</title>
  <body>
    <div id="root">Options page OK ✅</div>
    <script type="module" src="./options.ts"></script>
  </body>
</html>

src/options.ts

const root = document.getElementById("root") as HTMLDivElement;
root.textContent = "Options page OK ✅ (TypeScript)";

5. ビルド → 読み込み → 動作確認

npm run build
# distディレクトリが生成されたことを確認して下さい。
  1. 「chrome://extensions」を Chrome で開く
  2. 「デベロッパーモード」ON
  3. 「パッケージ化されていない拡張機能を読み込む」
  4. 生成された dist を指定
  • ✅️ Content: 新しいタブで任意のページの DevTools Console に "[ext] content loaded on:"が表示されること
  • ✅ Popup: ブラウザ右上の拡張アイコンをクリックして表示
  • ✅ Background: 拡張詳細 →「Service Worker」→ Console に onInstalled ログ
    • もし表示されなかったら拡張詳細右上の更新ボタンを押してみて下さい
  • ✅ Options: 拡張詳細 →「拡張機能のオプション」で表示

お疲れ様でした。それでは Step 2: 「開発用の監視/ホットリロードと、最小の UI 調整」に続きます。
https://github.com/Igusaya/chrome-extension-start/tree/vite%2Bts_chrome_ex_1

Discussion