🔨
Vite + TypeScript で作る Chrome 拡張(MV3) Step1
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ディレクトリが生成されたことを確認して下さい。
- 「chrome://extensions」を Chrome で開く
- 「デベロッパーモード」ON
- 「パッケージ化されていない拡張機能を読み込む」
- 生成された dist を指定
- ✅️ Content: 新しいタブで任意のページの DevTools Console に "[ext] content loaded on:"が表示されること
- ✅ Popup: ブラウザ右上の拡張アイコンをクリックして表示
- ✅ Background: 拡張詳細 →「Service Worker」→ Console に onInstalled ログ
- もし表示されなかったら拡張詳細右上の更新ボタンを押してみて下さい
- ✅ Options: 拡張詳細 →「拡張機能のオプション」で表示
お疲れ様でした。それでは Step 2: 「開発用の監視/ホットリロードと、最小の UI 調整」に続きます。
Discussion