Save & Persistence for Browser Games (localStorage vs IndexedDB, versioned saves, serialization, autosave)

Consolidated from MDN storage docs and the idb library (see Sources). Focus: what an AI builder needs so saves survive updates, don't corrupt, and don't block the frame — the usual bugs are lost progress on a schema change, quota errors, and jank from synchronous writes.

1. Pick the right storage

localStorage — simple key/value, synchronous, string-only, ~5MB per origin.

Good for: small settings, high scores, current-level, a single small save blob, key bindings, volume.
Synchronous = it blocks the main thread. Fine for occasional small writes; do NOT write large/frequent blobs to it every frame (causes hitches). Values must be strings → JSON.stringify/parse.
sessionStorage = same API but cleared when the tab closes (use for transient state only).

IndexedDB — asynchronous, transactional, large (hundreds of MB to GB, quota-based), stores structured data (objects, arrays, Blob, ArrayBuffer, typed arrays via the structured clone algorithm — no manual JSON needed).

Good for: big/complex saves, multiple save slots, replays, generated assets/level caches, offline data.
The raw API is verbose/callbacky — use the idb wrapper (Jake Archibald) for a clean promise-based API. Don't hand-roll raw IndexedDB.

Rule of thumb: settings/scores/small single save → localStorage; anything large, multi-slot, binary, or frequently written → IndexedDB (via idb). Cookies are the wrong tool for game saves (tiny, sent on every request).

Cache API / service worker is for caching the game itself (assets, offline PWA), not for player save data.

2. ALWAYS version your saves (the #1 lost-progress bug)

Your save schema will change between game versions. If you JSON.parse an old save into new code with no version handling, you get crashes or silent corruption and angry players who lost progress.

Rule: every save carries a version number, and you write migration steps between versions.

const SAVE_VERSION = 3;
function migrate(save) {
  let s = { ...save };
  if (s.version === 1) { s.coins = s.gold ?? 0; delete s.gold; s.version = 2; }
  if (s.version === 2) { s.settings = { ...defaults.settings, ...s.settings }; s.version = 3; }
  return s; // now at SAVE_VERSION
}
function loadSave(raw) {
  let save = raw ?? structuredClone(defaultSave);
  if (save.version !== SAVE_VERSION) save = migrate(save);
  return save;
}

Migrations run in sequence (v1→v2→v3) so any old save upgrades.
IndexedDB has its own schema versioning via the open(name, version) + onupgradeneeded/idb's upgrade callback — use it to create/alter object stores. That's separate from your data version above; you often want both.
New fields: merge over defaults ({ ...defaults, ...loaded }) so older saves gain new keys with sane values instead of undefined.
Keep a backup of the previous save before overwriting, so a failed migration/corruption is recoverable.

3. Serialization: what to save

Save state, not behavior. Serialize plain data (positions, inventory, flags, RNG seed + counters). Never try to serialize class instances/functions/DOM/engine objects directly.
Save the seed + progress, not the whole generated world, for procgen games — regenerate deterministically on load (see procgen skill). Massively smaller and robust.
Use structuredClone / IndexedDB for objects with Map/Set/Date/typed arrays; plain JSON drops those (Map→{}, Date→string, undefined/functions omitted, NaN/Infinity→null). If using JSON, convert them explicitly.
Wrap every load in try/catch. Corrupt/partial JSON must fall back to defaults, not white-screen the game.
Consider a checksum or at least shape-validation of loaded data before trusting it. For competitive/leaderboard games remember client saves are trivially editable — validate server-side, don't trust local high scores.

4. Autosave (do it safely)

Autosave on meaningful events (level complete, checkpoint, item gained) and on a throttled timer — not every frame.
Debounce/throttle writes (e.g. at most once every few seconds) to avoid thrashing storage and causing jank; coalesce rapid changes.
Save on visibilitychange (hidden) and pagehide/beforeunload — mobile browsers kill backgrounded tabs without firing beforeunload reliably, so visibilitychange → hidden is the most reliable "player is leaving" signal. Do a final synchronous-ish flush there (localStorage) or a queued IndexedDB write.
Write atomically: for IndexedDB use a transaction; for localStorage, build the full string then set it once (a half-written multi-key save = corruption). Keep the previous save until the new one is confirmed.
Give visible feedback ("Saved") and expose manual save/load + multiple slots where appropriate.

5. Quota, availability & privacy gotchas

Storage can throw or be disabled: private/incognito mode, quota exceeded (QuotaExceededError), or blocked third-party storage. Feature-detect and wrap in try/catch; degrade gracefully (in-memory only) rather than crashing.
Eviction: browsers can clear storage under pressure ("best-effort" default). For important saves, request navigator.storage.persist() to reduce eviction risk, and check navigator.storage.estimate() for usage/quota.
Storage is per-origin; a domain change loses saves. iOS Safari has historically been aggressive about clearing storage from rarely-visited sites — don't treat browser storage as permanent; offer export/import (download/upload a save file) for anything precious, and cloud save for accounts.
localStorage blocks the main thread — keep values small; move big/async work to IndexedDB.

6. Bug-prevention checklist

No version field → old saves crash new builds / silent data loss; version + sequential migrations.
Parsing without try/catch → corrupt save white-screens the game; fall back to defaults.
Merging loaded save without defaults → new fields are undefined; spread over defaults.
JSON round-trip of Map/Set/Date/typed arrays → data silently lost; use structuredClone/IndexedDB or convert explicitly.
Frequent/large localStorage.setItem → main-thread hitches; throttle + use IndexedDB for big data.
No save on tab hide → mobile players lose progress; save on visibilitychange/pagehide.
Non-atomic multi-key writes → partial/corrupt saves; write one blob / use a transaction, keep a backup.
Assuming storage always works → crashes in private mode / over quota; feature-detect + try/catch + graceful degrade.
Trusting local high scores → trivially cheatable; validate server-side for leaderboards.
Saving the whole procgen world → bloated saves; save seed + progress and regenerate.

Defaults to apply

Ship a tiny save module by default: save(state) / load() with a version field + sequential migrate(), try/catch → defaults, and merge-over-defaults. This single pattern prevents the most damaging bug (progress lost on update).
Storage routing rule baked in: settings/scores/small save → localStorage; large/multi-slot/binary/frequent → IndexedDB via idb.
Autosave defaults: save on checkpoints + throttled timer + visibilitychange/pagehide, written atomically with a retained backup.
Persist the seed, not the world for procgen; offer export/import for precious saves and request storage.persist(). Never trust local scores for leaderboards.

Sources

MDN — Web Storage API (localStorage/sessionStorage): https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API
MDN — IndexedDB API + Using IndexedDB (versioning/onupgradeneeded): https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API , https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API/Using_IndexedDB
MDN — Structured clone algorithm (what serializes): https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm ; structuredClone(): https://developer.mozilla.org/en-US/docs/Web/API/structuredClone
MDN — Storage quotas & eviction / navigator.storage: https://developer.mozilla.org/en-US/docs/Web/API/Storage_API/Storage_quotas_and_eviction_criteria , https://developer.mozilla.org/en-US/docs/Web/API/StorageManager/persist
MDN — Document.visibilitychange / Page Visibility API: https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API
idb (promise-based IndexedDB wrapper, Jake Archibald): https://github.com/jakearchibald/idb
web.dev — "Storage for the web" (choosing storage): https://web.dev/articles/storage-for-the-web
localForage (localStorage-like API over IndexedDB): https://github.com/localForage/localForage

8.8 KiB Raw Permalink Blame History