Chrome拡張機能の基本構成｜manifest.json・popup・content scriptの役割
Chrome拡張機能を作ろうとすると、最初に戸惑いやすいのがファイル構成です。
Webページなら、まず index.html を作って、必要に応じてCSSやJavaScriptを追加するイメージを持ちやすいかもしれません。ところがChrome拡張機能では、manifest.json、popup.html、popup.js、content.js、background.js、icons/ など、最初から複数のファイル名が出てきます。
名前だけを見ると難しそうですが、それぞれの役割を分けて考えると理解しやすくなります。
Chrome拡張機能は、ひとつの大きなファイルで全部を動かすというより、「設定を書くファイル」「アイコンを押したときの画面」「開いているWebページ上で動く処理」「裏側でイベントを受け取る処理」というように、役割ごとにファイルを分けて作ります。
この記事では、Chrome拡張機能の基本構成を初心者向けに整理します。細かい実装手順やManifest V3の詳しい仕様は後続記事で扱い、今回はまず「どのファイルが何を担当するのか」をつかむことを目的にします。
Chrome拡張機能は複数ファイルで役割分担する
Chrome拡張機能は、ブラウザに追加する小さなアプリのようなものです。
ただし、通常のWebアプリとは違い、拡張機能にはブラウザ側へ「この拡張機能は何をします」「どのファイルを使います」「どの権限が必要です」と伝える必要があります。
その中心になるのが manifest.json です。
さらに、拡張機能アイコンを押したときに出る小さな画面を作るなら popup.html や popup.js を使います。開いているWebページの中で動く処理を書くなら content.js を使います。裏側のイベント処理やメッセージの受け渡しには、Manifest V3では service worker として動く background.js を使うことがあります。
最初は、すべてを完璧に覚える必要はありません。
まずは次のように考えると分かりやすいです。
| 部品 | ざっくりした役割 |
|---|---|
manifest.json | 拡張機能全体の設定を書く |
popup.html | アイコンを押したときに表示する画面を作る |
popup.js | popup画面のボタン操作などを処理する |
content.js | 開いているWebページ上で動く |
background.js | 裏側のイベント処理を担当する |
icons/ | ツールバーやストア表示用の画像を置く |
この一覧を頭に入れておくだけでも、Chrome拡張機能の構成はかなり見通しやすくなります。
最小構成のフォルダ例
Chrome拡張機能の基本的なフォルダ構成は、たとえば次のようになります。
my-extension/
├─ manifest.json
├─ popup.html
├─ popup.js
├─ content.js
├─ background.js
└─ icons/
├─ icon16.png
├─ icon48.png
└─ icon128.pngすべての拡張機能で、これらのファイルを必ず全部使うわけではありません。
たとえば、アイコンを押したときの画面だけを作るなら、最初は manifest.json、popup.html、popup.js だけでも考えられます。
逆に、開いているWebページにボタンを追加したいなら、content.js が重要になります。
通知、右クリックメニュー、拡張機能内のイベント処理などを扱う場合は、background.js や service worker の出番が出てきます。
つまり、フォルダ構成は作りたい機能によって変わります。ただし、manifest.json が中心になり、そこから必要なファイルを指定していく、という考え方は共通です。
manifest.json の役割
manifest.json は、Chrome拡張機能の設定ファイルです。
拡張機能の名前、説明、バージョン、使うファイル、表示するアイコン、必要な権限などをここに書きます。
Chromeはこのファイルを見て、拡張機能をどう読み込むかを判断します。人間にとっての説明書というより、Chromeに渡す設定書のようなものです。
たとえば、非常に簡略化すると次のような情報を持ちます。
{
"manifest_version": 3,
"name": "Sample Extension",
"version": "1.0.0",
"action": {
"default_popup": "popup.html"
}
}これはあくまで説明用の短い例です。実際には、作りたい機能に応じて、アイコン、権限、content script、background service worker などの設定を追加します。
初心者がまず理解しておきたいのは、manifest.json が「拡張機能全体の入口」だということです。
どのHTMLをpopupとして使うのか。どのJavaScriptをWebページ上で動かすのか。裏側で動くservice workerは何か。こうした関係を、manifest.json でChromeに伝えます。
Manifest V3の細かい書き方や権限設定は、後続の記事で詳しく扱う予定です。この記事では、まず manifest.json は拡張機能全体の設定ファイルだと押さえておけば十分です。
popup.html と popup.js の役割
popup.html は、拡張機能のアイコンを押したときに表示される小さな画面です。
Chromeの右上にある拡張機能アイコンをクリックすると、小さなパネルが開く拡張機能があります。設定を変更したり、ボタンを押したり、簡単な情報を表示したりする画面です。
その画面を作るのが popup.html です。
そして、popup画面内のボタン操作や入力処理を担当するのが popup.js です。
たとえば、次のような用途があります。
- 保存ボタンを押したときの処理を書く
- 入力欄の値を読み取る
- 設定値を表示する
- 開いているタブの情報を取得する
- content script や background service worker にメッセージを送る
popupは、ユーザーが拡張機能を操作するための小さな入口です。
ただし、popupは常に表示され続ける画面ではありません。ユーザーがアイコンを押したときに開き、閉じると画面も閉じます。そのため、長く保持したいデータはpopup内だけに置かず、chrome.storage や IndexedDB などに保存する設計を考えることがあります。
初心者向けに言えば、popup.html は見た目、popup.js はpopup画面の動き、と分けて考えると理解しやすいです。
content.js の役割
content.js は、開いているWebページ上で動く処理を書くファイルです。
Chrome拡張機能らしい機能を作るとき、この content script が重要になることが多いです。
たとえば、以下のような処理に使います。
- WebページのタイトルやURLを取得する
- ページ内のテキストを読み取る
- 特定のボタンや入力欄を探す
- Webページ上に独自のボタンを追加する
- 表データを読み取って加工する
- 特定のページだけで処理を動かす
前の記事で説明したように、Chrome拡張機能は「今開いているWebページに関われる」ことが大きな特徴です。その役割を担当するのが content script です。
たとえば、ECサイトの商品ページ上に「この商品を保存」ボタンを追加する場合、ページ上にボタンを挿入する処理は content.js に書くことが多くなります。
YouTube Liveのページでコメント欄の情報を読み取りたい場合も、ページ内の要素にアクセスする処理は content script の領域になります。
ただし、content script は何でも自由にできる魔法の場所ではありません。対象ページや権限の設定、ページ構造の変化、セキュリティ上の制約を考える必要があります。
この記事では深入りしませんが、まずは content.js は「Webページ側で動く処理」と覚えておくとよいです。
background.js と service worker の役割
background.js は、拡張機能の裏側で動く処理を担当するファイルです。
Manifest V3では、従来の常駐型background pageではなく、service worker として扱うのが基本です。
service worker は、必要なイベントが発生したときに動く裏側の処理です。たとえば、拡張機能内のメッセージを受け取ったり、右クリックメニューの操作を処理したり、通知やイベントに反応したりします。
初心者向けには、background.js は「表に出ない裏方の処理」と考えると分かりやすいです。
popupはユーザーが開いたときに表示される画面です。content scriptはWebページ上で動きます。background service workerは、必要なタイミングで裏側のイベントを処理します。
たとえば、popupから「今のページ情報を保存して」と依頼し、background service worker が保存処理や他の処理につなぐ、という構成が考えられます。
ただし、Manifest V3のservice workerにはライフサイクルがあります。常に動き続ける前提で書くと、思った通りに動かないことがあります。
このあたりは少し細かい話になるため、この記事では概要に留めます。詳しくは、Manifest V3やservice workerを扱う記事で整理します。
icons フォルダと画像ファイルの役割
icons/ フォルダには、拡張機能で使うアイコン画像を置きます。
アイコンは、Chromeのツールバー、拡張機能管理画面、Chrome Web Storeの掲載画面などで使われます。
よく使われるサイズとして、16px、48px、128pxなどがあります。実際に必要なサイズや指定方法は、用途や公開時の要件に合わせて確認します。
フォルダ例では次のように置いていました。
icons/
├─ icon16.png
├─ icon48.png
└─ icon128.pngアイコンは小さな画像ですが、公開する拡張機能ではかなり重要です。ユーザーがツールバーやストアで最初に見る要素になるからです。
ただし、開発の最初から完璧なデザインを用意する必要はありません。まずは動作確認用のアイコンを用意し、公開前に見やすく権利的にも問題のない画像へ整える、という進め方でも構いません。
ファイル同士の関係をざっくり見る
Chrome拡張機能では、ファイル同士が役割を分担しながら動きます。
たとえば、ユーザーが拡張機能アイコンを押したとします。
そのとき、manifest.json の設定に従って popup.html が表示されます。popup内のボタンを押すと popup.js が動きます。必要に応じて、popupからcontent scriptへ「ページの情報を取ってきて」と依頼したり、background service workerへ「保存処理をして」と依頼したりします。
一方、content.js はWebページ上で動き、ページタイトルやURL、特定の要素などを扱います。
background.js は裏側でメッセージやイベントを受け取り、拡張機能全体の処理をつなぐ役割を持つことがあります。
この関係を一言でまとめると、次のようになります。
manifest.json
├─ popup.html / popup.js
├─ content.js
├─ background.js
└─ icons/manifest.json が全体の設定を持ち、そこから必要な画面や処理が読み込まれる、というイメージです。
初心者が混乱しやすいポイント
Chrome拡張機能の基本構成で、初心者が混乱しやすいポイントはいくつかあります。
まず、popup.js と content.js の違いです。
popup.js はpopup画面の中で動きます。ユーザーが拡張機能アイコンを押して開いた小さな画面の処理です。
一方、content.js はWebページの中で動きます。ページ上のボタンやテキスト、入力欄などに関わる処理です。
次に、background.js がどこで動くのかも混乱しやすいです。これは画面として表示されるものではなく、裏側でイベントを処理するためのものです。Manifest V3ではservice workerとして扱うため、「ずっと動き続ける裏画面」と考えると誤解することがあります。
また、manifest.json はJavaScriptではありません。JSON形式の設定ファイルです。コメントを書けない、カンマの位置に注意が必要、といったJSONとしてのルールがあります。
さらに、ファイル名やパスの指定ミスもよくあります。manifest.json に popup.html と書いているのに、実際のファイル名が pop.html になっていると読み込めません。content.js のパスを間違えても動きません。
最初は、構成を小さくして確認するのが大切です。いきなり複雑な拡張機能を作るのではなく、popupだけ、content scriptだけ、保存だけ、というように小さく動作確認していくと理解しやすくなります。
まとめ
Chrome拡張機能は、複数のファイルで役割を分担して動きます。
中心になるのは manifest.json です。ここに拡張機能の名前、バージョン、使うファイル、権限などを設定します。
popup.html と popup.js は、拡張機能アイコンを押したときに表示される画面と、その画面の処理を担当します。
content.js は、開いているWebページ上で動く処理です。ページの情報を取得したり、ボタンを追加したりする場面で重要になります。
background.js は、Manifest V3ではservice workerとして、裏側のイベント処理を担当します。
icons/ には、ツールバーやストア掲載で使うアイコン画像を置きます。
最初は難しく見えますが、役割ごとに分けて考えれば整理しやすくなります。
次の実装系の記事では、この基本構成をもとに、実際に最小構成のChrome拡張機能を作る流れへ進めます。
Your Message