Browser Storage skill for Codex

Pick the store by data shape, size, lifetime and who must read it (JS, the server, a service worker). Done well: data survives exactly as long as intended, writes cannot silently fail, schema changes migrate old data, and nothing an attacker’s script could steal sits in script-readable storage.

Choose the store

Need	Store	Limits and behaviour
Small UI prefs (theme, collapsed panels)	localStorage	~5 MB per origin, strings only, synchronous (blocks main thread)
Per-tab state (wizard step, scroll)	sessionStorage	Per tab, cleared on close; duplicated when a tab is duplicated
Structured app data, offline records, blobs	IndexedDB (via idb or Dexie)	Async, large (share of disk), indexes, transactions
HTTP responses and assets for offline	Cache API (usually from a service worker)	Request/response pairs
Large files, SQLite databases, random-access binary	OPFS (navigator.storage.getDirectory())	Fast sync access handles in workers only
Session identity, anything the server must read	Cookie, HttpOnly; Secure; SameSite=Lax	~4 KB each, sent on every matching request
Values that must not persist	Memory (module state, React state)	Gone on reload

Rules of thumb: never use localStorage for data over ~100 KB or written often (it is synchronous and serialises on every write); never use cookies for client-only data (bandwidth on every request); never put auth tokens in localStorage, sessionStorage or IndexedDB (any XSS reads them).

Before writing code

1. Read AGENTS.md; look for existing storage wrappers, key naming, and SSR framework.
2. Inventory current keys: search for localStorage., indexedDB.open, document.cookie, openDB(, new Dexie(. Name every key/database with an app prefix and version.
3. Decide lifetime and ownership per item: who writes, who reads, when it expires, what happens on logout.

Safe localStorage wrapper

type Stored<T> = { v: number; data: T; exp?: number };

export function createStore<T>(key: string, version: number, fallback: T, migrate?: (old: unknown, from: number) => T) {
  const fullKey = `acme:${key}`;
  return {
    get(): T {
      try {
        const raw = globalThis.localStorage?.getItem(fullKey);
        if (!raw) return fallback;
        const parsed = JSON.parse(raw) as Stored<unknown>;
        if (parsed.exp && Date.now() > parsed.exp) { localStorage.removeItem(fullKey); return fallback; }
        if (parsed.v !== version) return migrate ? migrate(parsed.data, parsed.v) : fallback;
        return parsed.data as T;
      } catch {
        return fallback;                 // corrupted JSON, storage disabled, SSR
      }
    },
    set(data: T, ttlMs?: number): boolean {
      try {
        const value: Stored<T> = { v: version, data, exp: ttlMs ? Date.now() + ttlMs : undefined };
        localStorage.setItem(fullKey, JSON.stringify(value));
        return true;
      } catch {
        return false;                    // QuotaExceededError, SecurityError: caller decides
      }
    },
    remove() { try { localStorage.removeItem(fullKey); } catch {} },
  };
}

Every read tolerates missing, corrupt and old-version data; every write reports failure. Access throws SecurityError when storage is blocked (some privacy settings, sandboxed iframes), so even localStorage itself must be inside try.

IndexedDB with idb

import { openDB, type DBSchema } from 'idb';

interface AppDB extends DBSchema {
  drafts: { key: string; value: { id: string; body: string; updatedAt: number }; indexes: { byUpdated: number } };
  outbox: { key: number; value: { url: string; body: unknown; createdAt: number } };
}

export const dbPromise = openDB<AppDB>('acme', 2, {
  upgrade(db, oldVersion, _newVersion, tx) {
    if (oldVersion < 1) {
      db.createObjectStore('drafts', { keyPath: 'id' });
    }
    if (oldVersion < 2) {
      tx.objectStore('drafts').createIndex('byUpdated', 'updatedAt');
      db.createObjectStore('outbox', { autoIncrement: true });
    }
  },
  blocked() { /* another tab holds an older version open: ask user to close it */ },
  blocking() { /* this tab blocks a newer version: close and reload */ },
});

export async function saveDraft(id: string, body: string) {
  const db = await dbPromise;
  await db.put('drafts', { id, body, updatedAt: Date.now() });
}

• Migrations are cumulative if (oldVersion < n) blocks; never edit a shipped block.
• Schema changes only happen in upgrade; bumping the version is the only way in.
• Transactions auto-commit when no requests are pending: do not await fetch() inside a transaction, it will be closed when you come back.
• Handle blocking by closing the connection, or users with two tabs get stuck.
• Dexie is a good alternative when you want a query API and live queries (useLiveQuery in React). Pick one and wrap it in a repository module.

Quota, persistence and eviction

const { usage, quota } = await navigator.storage.estimate();
const persisted = await navigator.storage.persisted?.();
// Ask only after a user action that signals intent (e.g. "make available offline")
const granted = await navigator.storage.persist?.();

• Default storage is “best effort”: the browser may evict it under disk pressure, least-recently-used origins first.
• Safari deletes script-writable storage (localStorage, IndexedDB, Cache API) for sites without user interaction in 7 days of browser use, unless the site is installed to the home screen. Treat client storage as a cache of server state for anything important.
• Private browsing modes give small, session-only quotas.
• On QuotaExceededError, evict your own oldest data (LRU by updatedAt index) and retry once; then degrade (stop caching) rather than crash.

Cookies

Set-Cookie: __Host-session=abc123; Path=/; Secure; HttpOnly; SameSite=Lax; Max-Age=1209600

Attribute	Rule
HttpOnly	Always for session or auth cookies
Secure	Always (required for SameSite=None and __Host-)
SameSite	Lax default; Strict for high-value actions; None only for real cross-site use
__Host- prefix	Locks to host, Path=/, no Domain: use for session cookies
Partitioned	Third-party embeds that need cookies under third-party cookie restrictions (CHIPS)

Client-side cookie reads and writes (document.cookie, cookieStore) are for non-sensitive values only. The server sets auth cookies.

Cross-tab sync

• window.addEventListener('storage', e => ...) fires in other tabs when localStorage changes (not in the tab that wrote it).
• For IndexedDB or app events, use BroadcastChannel:

const channel = new BroadcastChannel('acme-sync');
channel.postMessage({ type: 'draft-saved', id });
channel.onmessage = (e) => { if (e.data.type === 'logout') clearLocalData(); };

• On logout: clear IndexedDB stores and keys that belong to the user, broadcast logout, and have the server send Clear-Site-Data: "storage" if all origin storage should go.

OPFS for heavy data

Use OPFS with the official SQLite WASM build (or wa-sqlite) when you need SQL, large datasets, or file-like random access. Synchronous access handles (fileHandle.createSyncAccessHandle()) exist only in dedicated workers; run the database in a worker and talk to it via messages. Requires cross-origin isolation only for some SQLite VFS options; check the library’s docs for headers.

SSR and frameworks

• window, localStorage and indexedDB do not exist on the server. Read storage in effects (useEffect, onMounted) or client-only modules.
• Rendering stored preferences (theme) on the server causes hydration mismatch; put them in a cookie the server can read, or render a neutral state and update after mount.
• Persisted state libraries (zustand/middleware persist, Pinia plugins) need a version and migrate function just like hand-written stores.

Gotchas

• JSON.stringify drops undefined, turns Date into strings and Map/Set into {}; IndexedDB uses structured clone and keeps them.
• localStorage values are per origin: app.example.com and www.example.com do not share.
• sessionStorage is copied into a duplicated tab; unique per-tab ids must be regenerated.
• Storing PII client-side expands the data you must protect and delete on request; store the minimum and clear it on logout.
• Tests: jsdom has localStorage but no IndexedDB; use fake-indexeddb in unit tests and real-browser tests for quota and eviction behaviour.

Verification

• DevTools Application panel shows expected keys/stores with app prefix and version
• Old-version and corrupted data load without errors (seed them manually)
• Simulated quota exceeded (DevTools “custom storage quota”) degrades gracefully
• Two tabs: changes and logout propagate; IndexedDB upgrade with old tab open is handled
• No tokens or secrets in localStorage, sessionStorage or IndexedDB
• Logout clears user data in every store