Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 36 ยท Messaging and Storage

The chrome.storage API

Save extension data with chrome.storage.local, sync, session and managed, read and write with promises, set defaults, remove keys, and learn why storage beats localStorage and global variables in Manifest V3.

Almost every extension needs to remember something: a setting, a list of saved items, the last visited page. In Manifest V3 your service worker is stopped and restarted all the time, so a global variable is forgotten within seconds. You need real storage. chrome.storage is the API built for this, and it is available to every part of the extension, including content scripts.

You must declare the "storage" permission in manifest.json:

JSON
{
  "manifest_version": 3,
  "name": "Storage demo",
  "version": "1.0",
  "permissions": ["storage"]
}

The four storage areas

chrome.storage has several areas, each with its own purpose:

Area Lives Shared across devices Typical use
local On this computer, until removed No Data, caches, anything large (about 10 MB, more with unlimitedStorage)
sync Synced through the user's Chrome account Yes Small user settings (about 100 KB in total, 8 KB per item)
session In memory until the browser closes No Temporary state, secrets you do not want on disk (about 10 MB)
managed Set by an administrator through policy Read-only Company-wide configuration

Why not localStorage? It does not exist in a service worker, it is synchronous, it is shared with the web page when used in a content script (the page's own storage, not yours), and it stores strings only. chrome.storage works everywhere in the extension, is asynchronous, and stores JSON-compatible values directly.

Reading and writing

Every method returns a Promise when you do not pass a callback.

JavaScript
// real extension code
await chrome.storage.local.set({ theme: "dark", visits: 3 });

const { theme } = await chrome.storage.local.get("theme");
const all = await chrome.storage.local.get(null);          // everything
const withDefaults = await chrome.storage.local.get({ theme: "light", fontSize: 16 });

await chrome.storage.local.remove("visits");
await chrome.storage.local.clear();

Key points:

  • get("key") returns an object { key: value }, and returns {} when the key is missing.
  • get({ key: default }) fills in defaults for missing keys. It is the neatest way to read settings.
  • get(null) returns everything.
  • set takes an object of keys and values and merges at the top level: other keys are untouched, but a nested object is replaced as a whole.
  • Values must be JSON-compatible. A Date, Map, Set or class instance does not round trip: store a timestamp number and rebuild the object.
A chrome.storage stand-in

Choosing the right area

flowchart TD
    A["Need to store data"] --> B{"Must survive<br/>browser restart?"}
    B -- "No" --> S["storage.session"]
    B -- "Yes" --> C{"Small user setting<br/>that should follow the user?"}
    C -- "Yes" --> Y["storage.sync"]
    C -- "No" --> L["storage.local"]

Session for temporary state, sync for small settings, local for everything else.

Notes you will meet in practice:

  • sync has quotas: about 8 KB per item, 100 KB in total and a limit on writes per minute. Exceeding them rejects the promise, so catch errors.
  • session is cleared when the browser closes or the extension reloads. By default content scripts cannot read it; call chrome.storage.session.setAccessLevel({ accessLevel: "TRUSTED_AND_UNTRUSTED_CONTEXTS" }) in the worker to allow it.
  • Never store secrets in sync or local: they are not encrypted by your extension, and sync goes to Google's servers.
  • Storage is per extension; websites cannot read it.

A tiny settings helper

Wrap defaults in one place so every part of the extension agrees:

JavaScript
const DEFAULTS = { theme: "light", fontSize: 16, enabled: true };

export async function getSettings() {
  return chrome.storage.sync.get(DEFAULTS);
}

export async function saveSettings(patch) {
  await chrome.storage.sync.set(patch);
}

See Storage patterns for reacting to changes and migrating data between versions.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why can't a service worker rely on a global variable to remember data?

    The service worker is event driven and is terminated after a short idle time. Anything not saved to storage is lost.
  2. 2. What does chrome.storage.local.get({ theme: 'light' }) return when theme was never saved?

    When you pass an object, its values are used as defaults for missing keys.
  3. 3. Which area follows the user to their other computers?

    storage.sync is synced via the user's Chrome account, with small quotas. local stays on one machine.
  4. 4. Which value survives a round trip through chrome.storage unchanged?

    Values must be JSON-compatible. Store timestamps and arrays instead of Dates and Maps.
  5. 5. Which permission do you declare to use chrome.storage?

    The "storage" permission is required. unlimitedStorage only raises the quota of local storage.

Summary

  • Use chrome.storage, not globals or localStorage, in extensions; it needs the "storage" permission.
  • local is for data, sync for small settings, session for temporary state, managed for admin policy.
  • get accepts a key, a list, null or an object of defaults; set merges top-level keys.
  • Values must be JSON-compatible; mind the sync quotas and never store secrets.

Next: Storage Patterns