はじめに (対象読者・この記事でわかること)

この記事は、ブラウザ拡張機能の開発に興味がある方、または既存の拡張機能で設定や初期データをJSONファイルで管理したいと考えている方を主な対象としています。JavaScriptでの非同期処理やブラウザ拡張機能の基本的な知識があれば、よりスムーズに理解できるでしょう。

この記事を読むことで、以下のことがわかります。 - ブラウザ拡張機能内部に配置したJSONファイルを、JavaScriptを使って安全かつ非同期に読み込む具体的な方法。 - chrome.runtime.getURL() を使用して拡張機能内のリソースURLを取得する方法。 - fetch APIとasync/awaitを組み合わせた、実践的なファイル読み込み処理の実装。 - 拡張機能内でファイルを扱う際の注意点や、よくある問題とその解決策。

拡張機能に柔軟性を持たせ、メンテナンス性を向上させるための一歩を踏み出しましょう。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。 - HTML/CSSの基本的な知識 - JavaScriptの基本的な知識（特にPromise、async/await構文） - ブラウザ拡張機能の基本的な構造（manifest.jsonの役割など）

拡張機能でJSONファイルを扱う背景と課題

ブラウザ拡張機能を開発していると、定数データ、設定情報、多言語対応の文字列、あるいは複雑な初期データなどを拡張機能内に持たせたい場面が頻繁に訪れます。このようなデータをJavaScriptのコード内に直接ハードコードしてしまうと、データの変更がコードの修正を伴うことになり、保守性が低下します。そこで、構造化されたデータを管理するのに適したJSONファイルが非常に有用です。

JSONファイルにデータを分離することで、以下のメリットが得られます。 - データの可読性と保守性の向上: データがコードから分離され、独立して管理しやすくなります。 - 柔軟な設定管理: ユーザー設定や機能のON/OFFなどをJSONで管理し、動的に振る舞いを変えることが可能になります。 - 国際化（i18n）対応: 各言語の文字列をJSONファイルに格納し、必要な言語を読み込むことで多言語対応が容易になります。

しかし、ブラウザ拡張機能内でJSONファイルを読み込む際には、通常のWebページとは異なる特性と課題があります。ブラウザ拡張機能は、その性質上、セキュリティモデルが厳しく、ファイルシステムへの直接アクセスは制限されています。そのため、単純に相対パスでfetchを呼び出しても、ファイルが存在しない、あるいはアクセス権限がないといったエラーに遭遇することがあります。

この課題を解決し、拡張機能内部のJSONファイルを安全かつ確実に読み込む方法を学ぶことが、今回の記事の目的です。

ブラウザ拡張機能内部のJSONファイルを読み込む実践ガイド

ここでは、ブラウザ拡張機能内でJSONファイルを配置し、JavaScriptを使って読み込む具体的な手順を解説します。

ステップ1: 拡張機能の構造とJSONファイルの配置

まず、基本的なブラウザ拡張機能の構造と、JSONファイルの配置方法について見ていきましょう。

一般的なブラウザ拡張機能は、manifest.jsonをルートに持ち、HTML、CSS、JavaScriptファイルが配置されます。今回読み込むJSONファイルも、これらのリソースと同様に拡張機能のディレクトリ内に配置します。

例として、以下のようなファイル構造を想定します。

my-json-extension/
├── manifest.json
├── popup.html
├── popup.js
└── data/
    └── config.json
  • manifest.json: 拡張機能のメタデータや権限を定義するファイルです。
  • popup.html: 拡張機能のポップアップUIです。
  • popup.js: popup.htmlから読み込まれるJavaScriptファイルで、ここにJSON読み込みのロジックを記述します。
  • data/config.json: 読み込みたいJSONファイルです。今回は例として設定情報が書かれているとします。

data/config.jsonの内容は例えば以下のようになります。

Json

{
  "apiEndpoint": "https://api.example.com/v1",
  "theme": "dark",
  "features": {
    "notifications": true,
    "analytics": false
  },
  "defaultMessage": "Hello from config!"
}

manifest.jsonの記述:

manifest.jsonには、JSONファイルを読み込むために特別な権限や設定を記述する必要は通常ありません。これは、拡張機能内部のリソースへのアクセスはデフォルトで許可されているためです。ただし、もしコンテンツスクリプトから直接このJSONファイルを読み込む場合（fetchでURLを直接指定するのではなく、スクリプトのsrcとして指定するなど）、あるいは外部のウェブページからアクセス可能にしたい場合は、web_accessible_resourcesに記述する必要が生じることもあります。しかし、今回はpopup.js（拡張機能のコンテキスト）から読み込むため、その必要はありません。

最小限のmanifest.jsonの例を示します。（Manifest V3を前提とします）

Json

{
  "manifest_version": 3,
  "name": "JSON Reader Extension",
  "version": "1.0",
  "description": "拡張機能内部のJSONファイルを読み込むデモ",
  "action": {
    "default_popup": "popup.html",
    "default_icon": {
      "16": "icons/icon16.png",
      "48": "icons/icon48.png"
    }
  },
  "icons": {
    "16": "icons/icon16.png",
    "48": "icons/icon48.png",
    "128": "icons/icon128.png"
  },
  "permissions": []
}

ステップ2: JavaScriptでのJSONファイル読み込み処理

次に、popup.jsでdata/config.jsonを読み込むロジックを記述します。

ブラウザ拡張機能内部のリソースを読み込む際の鍵となるのが、chrome.runtime.getURL() メソッドです。このメソッドは、拡張機能パッケージ内の指定されたパスを持つリソースの完全な絶対URLを返します。このURLは、chrome-extension://<extension-id>/data/config.jsonのような形式になります。

この絶対URLを取得した後、標準の fetch API を使って非同期にファイルを読み込み、JSONとしてパースします。

popup.htmlの例:

Html

<!DOCTYPE html>
<html>
<head>
  <title>JSON Reader</title>
  <style>
    body { font-family: sans-serif; padding: 10px; min-width: 300px; }
    pre { background-color: #f0f0f0; padding: 10px; border-radius: 5px; white-space: pre-wrap; word-break: break-all; }
    h3 { margin-top: 0; }
  </style>
</head>
<body>
  <h3>読み込んだJSONデータ</h3>
  <pre id="displayArea">データを読み込み中...</pre>
  <script src="popup.js"></script>
</body>
</html>

popup.jsの例:

Javascript

/**
 * 拡張機能内部のJSONファイルを非同期で読み込む関数
 */
async function loadConfig() {
  const displayArea = document.getElementById('displayArea');

  try {
    // 拡張機能内のJSONファイルの絶対URLを取得
    // 'data/config.json' は manifest.json から見た相対パス
    const configUrl = chrome.runtime.getURL('data/config.json');
    console.log('JSONファイルの絶対URL:', configUrl);

    // fetch APIを使ってJSONファイルを読み込む
    const response = await fetch(configUrl);

    // HTTPレスポンスが正常（status 200-299）でない場合はエラーをスロー
    if (!response.ok) {
      throw new Error(`HTTPエラーが発生しました！ステータス: ${response.status} ${response.statusText}`);
    }

    // レスポンスボディをJSONとしてパース
    const config = await response.json();

    // 読み込んだJSONデータをコンソールに出力
    console.log('読み込んだ設定データ:', config);

    // 読み込んだデータをHTML要素に表示
    displayArea.textContent = JSON.stringify(config, null, 2);

  } catch (error) {
    // エラーが発生した場合の処理
    console.error('設定ファイルの読み込みに失敗しました:', error);
    displayArea.textContent = `エラー: ${error.message}\nコンソールを確認してください。`;
  }
}

// DOMの読み込みが完了したらJSONファイルを読み込む
document.addEventListener('DOMContentLoaded', loadConfig);

解説:

  1. chrome.runtime.getURL('data/config.json'): この行が最も重要です。'data/config.json'は、拡張機能のルートディレクトリからの相対パスです。getURL()はこれを、ブラウザが拡張機能のリソースとして認識できる完全なURL（例: chrome-extension://abcdefghijlkmnopqrstuvwxyz/data/config.json）に変換します。
  2. await fetch(configUrl): 変換されたURLを使ってfetch APIを呼び出します。fetchはネットワークリクエストを行い、レスポンスをPromiseとして返します。awaitキーワードを使うことで、レスポンスが返ってくるまで処理を一時停止し、非同期処理を同期的に書くことができます。
  3. if (!response.ok): fetchリクエストが成功しても、HTTPステータスコードがエラーを示す場合があります（例: 404 Not Found, 500 Internal Server Error）。response.okプロパティは、レスポンスのステータスコードが200-299の範囲内である場合にtrueを返します。そうでない場合はカスタムエラーをスローし、catchブロックで処理します。
  4. await response.json(): レスポンスボディをJSON形式としてパースします。これも非同期処理であるため、awaitが必要です。
  5. try...catchブロック: 非同期処理では、エラーハンドリングが非常に重要です。tryブロック内で発生したエラーはcatchブロックで捕捉され、適切に処理することができます。

ハマった点やエラー解決

ブラウザ拡張機能でJSONファイルを読み込む際に遭遇しやすい問題と、その解決策をまとめます。

  1. 問題: JSONファイルが読み込めない（fetchでエラー、またはファイルが見つからない）

    • 原因1: chrome.runtime.getURL()を使用せず、相対パスで直接fetch('./data/config.json')などと記述してしまった。ブラウザ拡張機能のコンテキストでは、通常のWebページの相対パスとは異なるパス解決が行われます。
    • 原因2: JSONファイルのパスが間違っている。ファイル名やディレクトリ名にスペルミスがある。
    • 原因3: manifest.jsonにweb_accessible_resourcesが必要なケースで設定が漏れている。（今回のユースケースでは通常不要ですが、もしコンテンツスクリプトから特定のHTMLフレームワークのテンプレートとして読み込む場合など、外部からアクセスされる状況では必要になることがあります。）
    • 解決策:
      • 常にchrome.runtime.getURL()を使って絶対パスを取得し、それを使用してください。
      • ファイルパスが正しいか、スペルミスがないか、大文字小文字が合っているかを確認してください。
      • 開発者ツールのConsoleタブで、エラーメッセージやconfigUrlの出力（console.logで確認）をよく確認し、取得されたURLが正しいか検証してください。

  2. 問題: fetchがPromiseを返しているのにデータが取れない

    • 原因: awaitキーワードの使い忘れ。fetch()やresponse.json()はPromiseを返すため、それらの解決を待つ必要があります。awaitを使用しないと、Promiseオブジェクト自体が返ってきてしまい、期待するデータが得られません。
    • 解決策: const response = await fetch(configUrl); や const config = await response.json(); のように、必ずawaitを付けてPromiseが解決されるのを待つようにしてください。関数全体をasync関数として定義することも忘れないでください。

  3. 問題: 読み込んだJSONデータが不正、またはパースエラーになる

    • 原因: JSONファイルの構文エラー。カンマの抜け、クォーテーションの誤り、コメントの記述など、JSONの厳密なルールに違反している可能性があります。
    • 解決策: JSON Lintなどのオンラインツールを使って、data/config.jsonの構文が正しいか検証してください。非常に些細な構文エラーでもパースに失敗することがあります。

これらの問題を解決することで、より堅牢な拡張機能開発が可能になります。

まとめ

本記事では、JavaScriptブラウザ拡張機能で内部のJSONファイルを安全かつ効率的に読み込む方法 を解説しました。

  • 要点1: 拡張機能内部のJSONファイルへのパスは、chrome.runtime.getURL() を使って絶対URLに変換することが不可欠です。これにより、拡張機能のサンドボックス環境内でもファイルを確実に参照できます。
  • 要点2: 変換された絶対URLを元に、標準の fetch API を async/await と組み合わせて利用することで、非同期処理をシンプルかつ分かりやすく記述し、JSONデータを効率的に取得できます。
  • 要点3: ファイルが見つからない、ネットワークエラー、JSONの構文エラーなど、様々な問題に対応するために適切なエラーハンドリング（try...catchブロックやresponse.okのチェック）を行うことが重要です。

この記事を通して、拡張機能の設定やデータを外部ファイルとして管理できるようになり、拡張機能の柔軟性と保守性が向上したことでしょう。

今後は、読み込んだJSONデータを利用して拡張機能のUIを動的に変更したり、ユーザーが設定を保存・更新できる機能（chrome.storage APIとの組み合わせ）など、さらに発展的な内容についても記事にする予定です。

参考資料