chrome.storageとは？Chrome拡張機能で設定を保存する方法

公開日：2026/06/04

以前の記事「Chrome拡張機能とは？できること・Webアプリとの違い」では、Chrome拡張機能がブラウザ上の作業を補助できることを紹介しました。

Chrome拡張機能を使いやすくするには、利用者が選んだ設定を次回も引き継げるようにする必要があります。

たとえば、機能を有効にするか、通知を表示するか、どの表示形式を使うか、といった設定です。popupを閉じるたびに初期状態へ戻ってしまうと、利用者は毎回同じ操作を繰り返すことになります。

Chrome拡張機能では、こうした設定値を保存するために chrome.storage APIを使えます。

この記事では、初心者でも動きを確認しやすいように、popupのON/OFF設定を chrome.storage.local へ保存する小さな拡張機能を作ります。チェックボックスをオンにしてpopupを閉じ、もう一度開いたときもオンの状態が復元されることを確認します。

chrome.storageとは

chrome.storage は、Chrome拡張機能でデータを保存するためのAPIです。

拡張機能のpopup、content script、background service workerなどから利用できます。保存したデータは、キーと値の組み合わせで扱います。

たとえば、機能の有効・無効を表す設定は、次のような形で保存できます。

await chrome.storage.local.set({ enabled: true });

保存した値は、次のように取得できます。

const { enabled } = await chrome.storage.local.get("enabled");

ここでは、enabled がキー、true が値です。

設定値だけでなく、文字列、数値、配列、オブジェクトも保存できます。小さな設定画面を作る場合は、フォームの入力内容を保存し、次回表示時に読み込む処理が基本になります。

今回作るもの

今回は、拡張機能アイコンを押すと、小さなpopupが開くサンプルを作ります。

popupには「機能を有効にする」というチェックボックスを1個だけ配置します。

チェックを入れると、enabled: true を chrome.storage.local へ保存します。チェックを外すと、enabled: false を保存します。

popupを閉じて開き直すと、保存済みの値を読み込み、チェックボックスの状態を復元します。

今回の目的は、次の流れを理解することです。

manifest.json に storage 権限を書く
popup.html にチェックボックスを置く
popupを開いたときに get() で設定を読み込む
チェック状態が変わったときに set() で保存する
保存や読み込みに失敗したときは、利用者に分かるメッセージを出す

外部API通信、content scriptとのメッセージ通信、大量データの保存は扱いません。まずは設定値1個を確実に保存します。

localStorageではなくchrome.storageを使う理由

WebページのJavaScriptを書いた経験があると、localStorage を使いたくなるかもしれません。

しかし、Chrome拡張機能の設定保存では、基本的に chrome.storage を使います。

Chrome公式資料では、chrome.storage は拡張機能向けに用意された保存APIとして案内されています。拡張機能の複数のコンテキストから利用でき、保存領域を用途に応じて選べます。

一方、Web Storage APIの localStorage は、保存元のコンテキストに結び付いています。background service workerからはWeb Storage APIを使えません。また、content scriptで localStorage を使うと、拡張機能ではなく対象Webページ側の保存領域へ書き込むことになります。

保存方法	主な用途	注意点
`chrome.storage`	Chrome拡張機能の設定や小規模データ	拡張機能向けの保存API
`localStorage`	通常のWebページ内での小規模保存	拡張機能の複数コンテキスト共有には向かない
IndexedDB	履歴、ログ、一覧などのまとまったデータ	設計や実装が少し複雑になる

小さなON/OFF設定を保存する今回の用途では、chrome.storage.local が分かりやすい選択です。

保存領域の種類

chrome.storage には複数の保存領域があります。

保存領域	特徴	向いている用途
`chrome.storage.local`	ローカル端末へ保存する	一般的な設定、小規模データ
`chrome.storage.sync`	同期を有効にしているブラウザ間で設定を共有できる	少量の利用者設定
`chrome.storage.session`	ブラウザのセッション中だけメモリ上へ保持する	一時的な状態
`chrome.storage.managed`	管理者ポリシーで設定を配布する	組織向けの管理設定

この記事では、最初に覚えやすい chrome.storage.local を使います。

ローカル端末へ保存するため、popupを閉じても設定が残ります。拡張機能をいったん無効化して再度有効化した場合や、ブラウザを再起動した場合も、通常は保存済み設定を読み込めます。

複数端末で設定を共有したい場合は sync を検討できます。ただし、保存できる量や書き込み回数には制限があります。何でも同期するのではなく、少量の設定に限定して使います。

ファイル構成

今回のフォルダ構成は次の通りです。

storage-setting-extension/
├─ manifest.json
├─ popup.html
├─ popup.css
└─ popup.js

役割は次の通りです。

ファイル	役割
`manifest.json`	`storage` 権限とpopup画面を設定する
`popup.html`	チェックボックスと状態メッセージを表示する
`popup.css`	popupの見た目を整える
`popup.js`	保存済み設定の読み込みと変更時の保存を行う

content scriptやbackground service workerは使いません。

保存処理を理解しやすくするため、popupの中だけで完結する構成にします。

manifest.jsonにstorage権限を追加する

まず、manifest.json を作ります。

{
  "manifest_version": 3,
  "name": "Storage Setting Extension",
  "version": "1.0.0",
  "description": "popupのON/OFF設定を保存するサンプルです。",
  "permissions": ["storage"],
  "action": {
    "default_popup": "popup.html"
  }
}

今回の中心は、次の行です。

"permissions": ["storage"]

chrome.storage APIを使うため、storage 権限を追加します。

popup画面は、action.default_popup で指定します。

"action": {
  "default_popup": "popup.html"
}

今回はWebページへ処理を追加しないため、host_permissions や content_scripts は不要です。

必要な権限だけを追加すると、拡張機能の役割が分かりやすくなります。公開を考える場合も、なぜその権限が必要なのかを説明しやすくなります。

popup.htmlでチェックボックスを作る

次に、popup.html を作ります。

<!doctype html>
<html lang="ja">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Storage Setting</title>
    <link rel="stylesheet" href="popup.css">
  </head>
  <body>
    <main class="popup">
      <h1>表示設定</h1>
      <label class="setting-row">
        <input id="enabled-setting" type="checkbox">
        <span>機能を有効にする</span>
      </label>
      <p id="status-text" aria-live="polite">設定を読み込み中です</p>
    </main>
    <script src="popup.js"></script>
  </body>
</html>

設定値を操作するチェックボックスには、enabled-setting というIDを付けています。

<input id="enabled-setting" type="checkbox">

保存結果を表示する要素も用意します。

<p id="status-text" aria-live="polite">設定を読み込み中です</p>

保存に成功したのか、読み込みに失敗したのかを表示できると、動作確認がしやすくなります。利用者にとっても、操作結果が分かりやすくなります。

popup.js は、HTML要素の後で読み込みます。

<script src="popup.js"></script>

これにより、JavaScriptを実行するときには、チェックボックスと状態メッセージの要素を取得できます。

popup.cssで見た目を整える

次に、popup.css を作ります。

body {
  margin: 0;
  font-family: system-ui, sans-serif;
  color: #1f2937;
  background: #f8fafc;
}

.popup {
  width: 260px;
  padding: 16px;
}

h1 {
  margin: 0 0 14px;
  font-size: 18px;
}

.setting-row {
  display: flex;
  gap: 8px;
  align-items: center;
  padding: 12px;
  border: 1px solid #bfdbfe;
  border-radius: 8px;
  background: #ffffff;
}

#status-text {
  min-height: 1.5em;
  margin: 12px 0 0;
  color: #475569;
  font-size: 13px;
}

CSSは保存処理そのものには影響しません。

ただし、サンプルを試すときに、どの設定を操作しているか、保存結果がどこへ表示されるかが見やすい状態にしておくと理解しやすくなります。

popup.jsで保存と復元を実装する

次に、popup.js を作ります。

const enabledSetting = document.getElementById("enabled-setting");
const statusText = document.getElementById("status-text");

function updateStatus(enabled, prefix) {
  statusText.textContent = `${prefix}: ${enabled ? "ON" : "OFF"}`;
}

async function loadSetting() {
  const { enabled = false } = await chrome.storage.local.get("enabled");

  enabledSetting.checked = enabled;
  updateStatus(enabled, "読み込みました");
}

async function saveSetting() {
  const enabled = enabledSetting.checked;

  await chrome.storage.local.set({ enabled });
  updateStatus(enabled, "保存しました");
}

enabledSetting.addEventListener("change", () => {
  saveSetting().catch((error) => {
    console.error("設定の保存に失敗しました", error);
    statusText.textContent = "設定を保存できませんでした";
  });
});

loadSetting().catch((error) => {
  console.error("設定の読み込みに失敗しました", error);
  statusText.textContent = "設定を読み込めませんでした";
});

最初に、HTML要素を取得します。

const enabledSetting = document.getElementById("enabled-setting");
const statusText = document.getElementById("status-text");

状態メッセージは、共通の関数で更新します。

function updateStatus(enabled, prefix) {
  statusText.textContent = `${prefix}: ${enabled ? "ON" : "OFF"}`;
}

保存済み設定を読み込む

popupを開いたときは、loadSetting() を実行します。

async function loadSetting() {
  const { enabled = false } = await chrome.storage.local.get("enabled");

  enabledSetting.checked = enabled;
  updateStatus(enabled, "読み込みました");
}

chrome.storage.local.get("enabled") で、enabled というキーの値を読み込みます。

const { enabled = false } = await chrome.storage.local.get("enabled");

初回起動時は、まだ値が保存されていません。

そこで、分割代入の初期値として false を指定しています。保存済みの値がなければ、チェックボックスをオフにします。

enabledSetting.checked = enabled;

変更された設定を保存する

チェックボックスが変更されたときは、saveSetting() を実行します。

async function saveSetting() {
  const enabled = enabledSetting.checked;

  await chrome.storage.local.set({ enabled });
  updateStatus(enabled, "保存しました");
}

enabledSetting.checked から、現在のチェック状態を取得します。

chrome.storage.local.set({ enabled }) で保存します。

これは、次のようなオブジェクトを保存する処理です。

{
  enabled: true
}

チェックを外した場合は、false が保存されます。

エラーを表示する

保存処理や読み込み処理は非同期です。

失敗する可能性があるため、サンプルでもエラーを表示します。

saveSetting().catch((error) => {
  console.error("設定の保存に失敗しました", error);
  statusText.textContent = "設定を保存できませんでした";
});

開発中はDevToolsのConsoleで詳細を確認できます。利用者には、popup内の状態メッセージで失敗したことを伝えます。

Chromeで動作確認する

4つのファイルを作ったら、Chromeで拡張機能を読み込みます。

手順は次の通りです。

Chromeで chrome://extensions を開く
右上のデベロッパーモードをオンにする
「パッケージ化されていない拡張機能を読み込む」を押す
storage-setting-extension フォルダを選ぶ
拡張機能アイコンを押してpopupを開く
「機能を有効にする」へチェックを入れる
「保存しました: ON」と表示されることを確認する
popupを閉じる
もう一度popupを開く
チェックが入った状態で「読み込みました: ON」と表示されることを確認する

次に、チェックを外して同じ確認をします。

popupを開き直したときにオフの状態が復元されれば、保存と読み込みの両方が動いています。

ファイルを変更した場合は、chrome://extensions で再読み込みボタンを押します。

popupを開いたまま修正しても、その画面には古いJavaScriptが残っています。いったんpopupを閉じ、拡張機能を再読み込みしてから開き直します。

よくあるエラーと注意点

storage権限を書き忘れる

manifest.json に storage 権限があるか確認します。

"permissions": ["storage"]

権限を追加した後は、拡張機能管理画面で再読み込みします。

キー名を統一する

保存時と読み込み時で、同じキー名を使います。

await chrome.storage.local.set({ enabled: true });
const { enabled } = await chrome.storage.local.get("enabled");

一方が enabled、もう一方が isEnabled になっていると、保存済みの値を取得できません。

初期値を決める

初回起動時は、保存済みデータがありません。

設定が存在しない場合にどう動くかを決めます。

const { enabled = false } = await chrome.storage.local.get("enabled");

今回のサンプルでは、未設定ならオフにします。

非同期処理の完了を待つ

get() と set() は非同期です。

await を使い、読み込みや保存が終わってから画面を更新します。

非同期処理を待たずに画面を書き換えると、保存に失敗していても成功したように見える場合があります。

設定画面を信頼しすぎない

将来、content scriptやbackground service workerでも保存値を使う場合は、それぞれの処理側でも値を読み込みます。

popupは閉じると終了します。popupの変数だけに状態を持たせず、必要な設定は chrome.storage から取得します。

秘密情報を安易に保存しない

chrome.storage.local は便利ですが、パスワード、秘密鍵、アクセストークンなどを無条件に保存する場所として考えてはいけません。

保存する情報を最小限にし、外部サービスと連携する場合は、認証方式、保存期間、削除方法、利用者への説明を設計します。

保存するデータを選ぶ

Chrome拡張機能では、すべてのデータを同じ場所へ保存する必要はありません。

用途に応じて保存方法を選びます。

データの例	保存先の候補	理由
機能のON/OFF	`chrome.storage.local`	小さな設定値として扱いやすい
表示モード	`chrome.storage.local` または `sync`	少量の利用者設定
一時的な処理状態	`chrome.storage.session`	セッション中だけ保持したい
コメント履歴	IndexedDB	件数が増える一覧データ
操作ログ	IndexedDBまたは外部サーバー	検索、集計、保持期間の設計が必要

今回のON/OFF設定は、chrome.storage.local に向いています。

一方、YouTube Liveのコメント履歴のように、時間とともに件数が増え、検索や一覧表示が必要になるデータはIndexedDBが向いています。

次の記事では、IndexedDBを使い、履歴データを保存する考え方を扱います。

設定項目が増えたときの考え方

今回のサンプルは、enabled という設定値1個だけを保存しました。

実際の拡張機能では、設定項目が少しずつ増えることがあります。

たとえば、次のような設定です。

機能を有効にするか
通知を表示するか
表示テーマを明るくするか、暗くするか
一覧に表示する件数

複数の設定を保存する場合も、基本は同じです。

await chrome.storage.local.set({
  enabled: true,
  showNotification: false,
  theme: "light",
  itemsPerPage: 20
});

必要なキーだけを取得することもできます。

const { theme = "light" } = await chrome.storage.local.get("theme");

複数のキーをまとめて取得することもできます。

const settings = await chrome.storage.local.get([
  "enabled",
  "showNotification",
  "theme",
  "itemsPerPage"
]);

設定項目が増えたら、キー名の付け方を統一します。

たとえば、通知を表示する値を、保存する場所によって notification、showNotification、isNotificationEnabled と呼び分けると、読み込み側で間違えやすくなります。

どのキーを保存するかを決め、popup、content script、background service workerで同じ名前を使います。

また、初期値も1か所で管理すると保守しやすくなります。

const DEFAULT_SETTINGS = {
  enabled: false,
  showNotification: false,
  theme: "light",
  itemsPerPage: 20
};

保存済みデータと初期値を組み合わせると、新しい設定項目を追加した場合も扱いやすくなります。

const savedSettings = await chrome.storage.local.get(DEFAULT_SETTINGS);

get() に初期値を含むオブジェクトを渡すと、未保存のキーには既定値を使えます。

小さなサンプルでは分割代入の初期値でも十分です。設定画面が大きくなったら、初期値をまとめる方法を検討します。

設定を削除して初期状態へ戻す

保存機能を作るときは、保存する処理だけでなく、初期状態へ戻す方法も考えます。

特定のキーだけを削除する場合は、remove() を使います。

await chrome.storage.local.remove("enabled");

この後に今回の loadSetting() を実行すると、保存済みの enabled がないため、初期値の false が使われます。

複数のキーを削除する場合は、配列で指定できます。

await chrome.storage.local.remove([
  "enabled",
  "showNotification"
]);

保存領域の内容をすべて削除する場合は、clear() を使えます。

await chrome.storage.local.clear();

ただし、実際の拡張機能で clear() を使う場合は注意が必要です。

利用者が残したい設定や、別機能が使っているデータまで削除する可能性があります。設定画面へ「初期設定に戻す」ボタンを付けるなら、削除対象を明確にし、確認メッセージを表示します。

まずは必要なキーだけを remove() する方が、影響範囲を小さくできます。

popup以外で保存値を使う場合

今回のサンプルは、popup内で保存と復元を完結させました。

しかし、実際にはcontent scriptやbackground service workerでも設定値を使うことがあります。

たとえば、前回の記事で作ったページ上の固定ボタンを、設定がオンのときだけ表示したい場合です。

その場合、content script側でも chrome.storage.local.get() を使い、設定を読み込みます。

const { enabled = false } = await chrome.storage.local.get("enabled");

if (!enabled) {
  return;
}

// 設定がONの場合だけ、ページ上へボタンを追加する

popupで設定を変更した直後に、すでに開いているページへ反映したい場合は、追加の設計が必要です。

たとえば、chrome.storage.onChanged で変更を監視する方法や、popupからcontent scriptへメッセージを送る方法があります。

この記事では、設定を保存して復元する基本に集中します。複数コンテキスト間の連携は、保存処理が動くことを確認してから追加すると、問題を切り分けやすくなります。

設定保存を実装するときの確認項目

小さな拡張機能でも、次の項目を確認しておくと保守しやすくなります。

保存するキー名を統一しているか
初回起動時の初期値を決めているか
保存と読み込みの失敗を確認できるか
設定を削除して初期状態へ戻せるか
popup以外で使う値をpopup内の変数だけに持たせていないか
履歴やログを設定値と同じ場所へ詰め込んでいないか
パスワードやアクセストークンを安易に保存していないか
利用者へ保存内容を説明できるか

設定保存はコード量が少なくても、拡張機能の使いやすさや信頼性に影響します。

まずはキーを少なく保ち、用途が増えた段階で保存先や構造を見直します。

今回のサンプルで分かること

今回の拡張機能では、設定保存の基本的な流れを確認できました。

manifest.json に storage 権限を追加する
chrome.storage.local.set() で設定を保存する
chrome.storage.local.get() で保存済み設定を読み込む
初回起動時の初期値を決める
popupを開き直したときに画面へ設定を反映する
非同期処理の完了を待つ
保存や読み込みの失敗を画面とConsoleへ表示する
小さな設定値と大量の履歴データを分けて考える

実際の拡張機能では、チェックボックスだけでなく、入力欄、選択欄、表示色、通知の有無なども同じ考え方で保存できます。

参考リンク

まとめ

この記事では、chrome.storage.local を使い、Chrome拡張機能のpopupで選んだON/OFF設定を保存しました。

manifest.json に storage 権限を追加し、chrome.storage.local.set() で保存、chrome.storage.local.get() で読み込みます。

初回起動時は保存済みデータがないため、初期値も決めます。今回は false を既定値にしました。

popupを閉じると、popup内のJavaScript変数は保持されません。しかし、chrome.storage.local へ保存しておけば、次にpopupを開いたときに設定を復元できます。

設定保存は、小さな業務効率化ツールでも重要です。

利用者が一度選んだ設定を引き継げると、毎回の操作を減らし、拡張機能を継続して使いやすくできます。

まずは設定値1個の保存から始め、必要に応じて表示設定や通知設定へ広げます。履歴やログのように件数が増えるデータは、次の記事で扱うIndexedDBを検討します。