mv3-storage

Chrome extension storage wrapper for Manifest V3 (MV3) — a type-safe wrapper over chrome.storage with defaults, atomic updates, and typed subscriptions. Works with local, sync, and session areas. Zero dependencies.

interface MyStore {
  count: number;
  user: { id: string; name: string } | null;
  prefs: { theme: "light" | "dark"; lang: string };
}

import { createStorage } from "mv3-storage";

const store = createStorage<MyStore>({
  area: "local",
  defaults: {
    count: 0,
    user: null,
    prefs: { theme: "light", lang: "en" },
  },
});

const count = await store.get("count");                 // typed: number
await store.set("user", { id: "1", name: "Ada" });      // typed: User | null
await store.update("count", (n) => n + 1);              // typed: number → number
const all = await store.getAll();                       // typed: MyStore

const off = store.subscribe("user", (next, prev) => {
  console.log("user changed", prev, "→", next);
});

Why

chrome.storage.local.get returns Promise<unknown>. Reading anything back means casting or hand-rolling type assertions on every call site. This package wraps the API with a single typed schema, automatic defaults, atomic update(key, fn), and a properly-typed subscription API.

Install

pnpm add mv3-storage
# or: npm i mv3-storage
# or: yarn add mv3-storage

Usage

Declare your schema

// src/shared/store.ts
import { createStorage } from "mv3-storage";

export interface AppStore {
  authToken: string | null;
  recentSearches: string[];
  preferences: { theme: "light" | "dark"; notifications: boolean };
}

export const store = createStorage<AppStore>({
  area: "sync",  // or "local" or "session"
  defaults: {
    authToken: null,
    recentSearches: [],
    preferences: { theme: "light", notifications: true },
  },
});

Use it anywhere

import { store } from "@/shared/store";

const token = await store.get("authToken");                  // string | null
await store.set("authToken", "xyz");
await store.update("recentSearches", (arr) => [...arr, "react", "vite"].slice(-10));

// React to changes
const off = store.subscribe("preferences", (next) => {
  document.body.dataset.theme = next.theme;
});

API

createStorage<S>(options) → Storage<S>

| Option | Type | Default | Notes | | --- | --- | --- | --- | | area | "local" \| "sync" \| "session" | "local" | Which chrome.storage area to use. | | defaults | S | required | Returned when a key has no stored value. Defines the schema's keys. |

Storage<S>

| Method | Returns | Notes | | --- | --- | --- | | get(key) | Promise<S[K]> | Returns the default when no value is stored. | | set(key, value) | Promise<void> | | | update(key, fn) | Promise<S[K]> | fn receives the current value and returns (or resolves to) the next. | | remove(key) | Promise<void> | Subsequent get returns the default. | | getAll() | Promise<S> | All keys merged with defaults. | | clear() | Promise<void> | Clears the entire area — including keys not in your schema. Use carefully. | | subscribe(key, fn) | () => void | Notified on every change to key in the chosen area. | | subscribeAll(fn) | () => void | Notified once per change batch with a Partial<S> of the new values. |

Storage area choice

| Area | Persistence | Quota | Notes | | --- | --- | --- | --- | | local | Until uninstall | ~10 MB | Per-device. The usual choice. | | sync | Synced via Google account | ~100 KB | Smaller quota; synced across devices. | | session | Cleared on browser restart | ~10 MB | In-memory; useful for ephemeral state. MV3-only. |

Caveat: update is not lock-protected

store.update(key, fn) reads, calls fn, then writes. If two callers race on the same key, the second wins. For most extension use cases this is fine (popup-only edits, single-SW writes); for genuinely concurrent writes, do the merge in your handler.

Demo extension

A runnable demo lives in example/. The popup edits a typed counter and preference settings; changes persist across popup re-opens and surface in the SW console via subscribe.

cd example
pnpm install
pnpm build
# then load example/dist/ via chrome://extensions → "Load unpacked"

See example/README.md for full instructions.

Related packages

Part of a small MV3 toolkit for Chrome / Edge / Firefox extensions by @graybearo:

• mv3-message-router — typed messaging between popup, content, and service worker
• mv3-keepalive — service-worker keepalive + durable alarms
• mv3-content-bridge — content-script ↔ page-context typed bridge
• chrome-extension-vite-react — Vite + React + TS MV3 starter
• chrome-extension-webpack-react — webpack + React + TS MV3 starter
• awesome-mv3 — curated list of MV3 tools, libraries, and resources

License

MIT — see LICENSE.