IndexedDB vs localStorage for Crash Recovery

This page is part of the LocalStorage & IndexedDB Sync Strategies guide, which sits under the broader Session State Persistence & Hydration Fallbacks coverage of client-side durability patterns.

The decision this page resolves #

Every crash-recovery implementation starts with the same fork in the road: does the recovery payload go into localStorage or IndexedDB? Teams that pick wrong discover it under pressure — either a checkout form silently truncates at the 5 MB QuotaExceededError boundary, or a debounced autosave stutters typing because a synchronous write is blocking the main thread on every keystroke. This guide gives you the axes that actually matter for crash recovery — not general storage advice — and a concrete recommendation you can apply without re-deriving it from first principles each time.

The short version: localStorage is a synchronous, main-thread-blocking, string-only key-value store with a hard ceiling around 5 MB and no transactional guarantees. IndexedDB is an asynchronous, transactional, structured-clone database with orders of magnitude more headroom and atomic commit/rollback semantics. For crash recovery specifically — where you need the last state to survive an ungraceful termination without corruption — that difference is not cosmetic; it determines whether your recovery path is reliable at all.

Comparing the two storage tiers #

The pattern in that table is consistent: localStorage wins on immediacy (synchronous, available pre-hydration) and loses on everything related to durability at scale (size, shape, atomicity, frequency). IndexedDB is the inverse. Crash recovery is fundamentally a durability problem, which is why the recommendation below leans heavily toward IndexedDB — with localStorage kept only for the narrow slice of the problem it is actually good at.

Recommendation #

Default to IndexedDB for anything beyond a few kilobytes, anything written more than occasionally, or anything where a half-committed write would corrupt the recovery path. That covers the majority of crash-recovery use cases — form state, editor content, cart contents, multi-step wizards. The pattern used for syncing React state to IndexedDB is the reference implementation: debounced writes, an oncomplete-gated promise, and rollback to the last committed snapshot on onerror/onabort.

Reserve localStorage for two narrow roles: a tiny boolean or short string flag (for example, “a recovery snapshot exists”) that must be readable synchronously before or during hydration, and — optionally — a small hot-path snapshot of the most recent state for the interval between paint and the first IndexedDB read resolving. Never store the full recovery payload in localStorage if it can grow past a few kilobytes or change more than a handful of times per session; both the size ceiling and the blocking write model will eventually cause a visible failure.

Dual-write pattern: synchronous flag + async payload #

When you need both — an instant synchronous signal and a durable large payload — write the flag first and let the full payload land asynchronously. The two writes are decoupled: the flag never waits on the transaction.

// dualWrite.ts
const FLAG_KEY = 'recovery_pending';
const DB_NAME = 'crash_recovery_v1';
const STORE = 'snapshots';
const RECORD_KEY = 'latest';

// Step 1: synchronous, main-thread flag — safe because it is tiny and rare
function markRecoveryPending(version: number): void {
  try {
    localStorage.setItem(FLAG_KEY, String(version));
  } catch {
    // QuotaExceededError here means the origin's 5 MB is already exhausted
    // by other keys; the async IndexedDB write below is unaffected.
  }
}

function clearRecoveryFlag(): void {
  localStorage.removeItem(FLAG_KEY);
}

// Step 2: asynchronous, transactional payload write
function openDB(): Promise<IDBDatabase> {
  return new Promise((resolve, reject) => {
    const req = indexedDB.open(DB_NAME, 1);
    req.onupgradeneeded = e => {
      const db = (e.target as IDBOpenDBRequest).result;
      if (!db.objectStoreNames.contains(STORE)) db.createObjectStore(STORE);
    };
    req.onsuccess = e => resolve((e.target as IDBOpenDBRequest).result);
    req.onerror = e => reject((e.target as IDBOpenDBRequest).error);
  });
}

export async function persistSnapshot(
  db: IDBDatabase,
  payload: unknown,
  version: number,
): Promise<void> {
  // Flag goes first and synchronously — it survives even if the tab
  // dies before the transaction below resolves.
  markRecoveryPending(version);

  await new Promise<void>((resolve, reject) => {
    const tx = db.transaction(STORE, 'readwrite');
    tx.objectStore(STORE).put({ payload, version }, RECORD_KEY);
    tx.oncomplete = () => resolve();
    tx.onerror = () => reject(tx.error);
    tx.onabort = () => reject(new Error('snapshot transaction aborted'));
  });

  // Only clear the flag once the durable write is confirmed committed.
  clearRecoveryFlag();
}

On startup, a pending flag with no matching committed version tells you the tab died mid-write — recover from the last committed IndexedDB record (there is nothing else to recover, since the interrupted write never committed) and clear the stale flag.

How to choose: numbered steps #

1. Measure the payload. Serialize a representative sample of the state and check its byte size. If it regularly exceeds a few kilobytes, localStorage is disqualified outright by the 5 MB ceiling and the cost of synchronous serialization on every write.
2. Count the writes per minute. Keystroke-level or interval-driven updates on localStorage block the main thread on each call; anything more frequent than an occasional save needs IndexedDB’s asynchronous transactions.
3. Decide how much atomicity you need. If a half-written value would leave the recovery path corrupted rather than merely stale, you need IndexedDB’s commit/rollback guarantee — localStorage offers no equivalent.
4. Check the data shape. Dates, Maps, Sets, Blobs, or deeply nested objects either need manual serialization for localStorage or get structured-clone support for free in IndexedDB.
5. Account for SSR and first paint. If a value must be read synchronously before or during hydration, only localStorage can serve that read; plan for IndexedDB to resolve slightly later.
6. Implement the dual-write if both constraints apply. Use the pattern above: flag first and synchronous, payload second and transactional, flag cleared only after the transaction commits.

Edge cases #

Verification steps #

1. Confirm the flag is synchronous. In DevTools Console, call your markRecoveryPending function and immediately read localStorage.getItem('recovery_pending') on the next line — it must already reflect the new value with no awaiting.
2. Confirm the payload write is non-blocking. Trigger a large persistSnapshot call and use the Performance panel to verify no long task appears on the main thread during the transaction; the blocking work should only be the localStorage.setItem call for the flag.
3. Simulate a crash between flag and commit. Call markRecoveryPending(), then throw before the transaction starts (or kill the tab). On reload, confirm your recovery logic detects a pending flag with no matching committed version and falls back to the last good IndexedDB record.
4. Check quota behavior for each tier. Use DevTools → Application → Storage to override the quota to a small value; confirm localStorage throws QuotaExceededError distinctly from any IndexedDB error, and that your dual-write code handles each independently.
5. Measure payload size in CI. Add an assertion that serializes representative state and fails the build if it exceeds your chosen localStorage budget (for example, 2 KB), catching drift before it reaches production.

Frequently asked questions #

Can I just use localStorage for everything and skip IndexedDB entirely?

Only if the state is genuinely tiny (a few KB) and writes are infrequent. Because localStorage writes are synchronous and block the main thread, using it for large or frequently updated state degrades interaction responsiveness and risks silent truncation near the 5 MB quota.

Is IndexedDB slower than localStorage for small, simple flags?

For a single boolean or short string read before first paint, localStorage is faster because it is synchronous with no transaction overhead. For anything larger or written repeatedly, IndexedDB’s asynchronous transactions outperform localStorage because they never block rendering.

What happens if the tab crashes between the localStorage write and the IndexedDB write in a dual-write setup?

The localStorage flag is written first and synchronously, so it will always be present even if the IndexedDB write never starts. On restart, check the flag: if it is set but the IndexedDB payload is missing or stale, treat the flag as a hint to recover from the last-known-good IndexedDB snapshot rather than trusting the flag’s own value as full state.

Related #

• LocalStorage & IndexedDB Sync Strategies — parent guide covering storage tier selection, quota trade-offs, and cross-origin constraints
• Syncing React State to IndexedDB for Crash Resilience — the debounced write and rollback pattern referenced above, applied to a full React state tree
• Handling QuotaExceededError When Persisting Session State — recovering gracefully when either storage tier hits its capacity ceiling