Chrome Extension Storage

Chrome extensions have four storage areas plus IndexedDB. Each serves a different purpose with different lifecycles, quotas, and trade-offs. Choose based on data size, persistence needs, and cross-device requirements.

Storage Selection Guide

When to Use What

`storage.session` — In-memory state that must be fast but doesn't need to survive browser restart. Service worker volatile cache. Authentication tokens for the current session.

`storage.local` — Default choice for most extension data. Settings, cached API responses, user data that stays on one device. Use unlimitedStorage permission to remove the 10 MB cap.

`storage.sync` — Small user preferences that should follow the user across devices. Subject to strict quotas: 8 KB per item, 512 items max, 1,800 writes/hour.

IndexedDB — Large datasets, binary data (images, model weights, video metadata), or data requiring structured queries. No JSON serialization overhead (uses structured cloning). Can use ~80% of available disk.

Data That Must Never Be Stored

• Passwords and credentials in storage.local or storage.sync — these are NOT encrypted. Use storage.session for temporary auth tokens (clears on browser close).
• Non-serializable objects — chrome.storage only accepts JSON-serializable types. No Date, Set, Map, RegExp, or class instances.

Write-Through Cache Pattern

For high-performance state management across service worker restarts:

// Service worker — write-through cache
let cache: AppState | null = null;

async function getState(): Promise<AppState> {
  if (!cache) {
    const result = await chrome.storage.local.get('appState');
    cache = result.appState ?? DEFAULT_STATE;
  }
  return cache;
}

async function setState(update: Partial<AppState>) {
  cache = { ...(await getState()), ...update };
  await chrome.storage.local.set({ appState: cache });
  // onChanged listeners in popups/side panels auto-update
}

Reactive Storage with WXT

WXT provides a reactive storage API with automatic change notifications:

import { storage } from 'wxt/storage';

const userSettings = storage.defineItem<Settings>('local:settings', {
  defaultValue: { theme: 'light' },
});

// Read
const settings = await userSettings.getValue();

// Write
await userSettings.setValue({ theme: 'dark' });

// Watch for changes (works across all contexts)
userSettings.watch((newValue) => {
  updateUI(newValue);
});

Quota Pitfalls

• Sync throttling: Exceeding 1,800 writes/hour silently fails. Batch updates.
• Sync per-item limit: Objects >8 KB fail. Shard large objects across keys.
• Session volatility: Lost on extension reload during development.
• JSON serialization overhead: Large objects in chrome.storage are slow. Use IndexedDB for large data.

Additional Resources

Reference Files

• `references/storage-guide.md` — Detailed storage patterns, IndexedDB usage, migration strategies, and React integration