Use localStorage for small synchronous flags (settings, a single save slug) under a few hundred KB. Switch to IndexedDB when you store larger structured data, binary assets, many records, or need async, non-blocking reads and writes – for example level data, asset caches or multiple save slots.
At a glance
| Fact | Value | Source |
|---|---|---|
| localStorage is synchronous and origin-scoped | blocks main thread | developer.mozilla.org |
| localStorage persists across browser restarts | same-origin only | developer.mozilla.org |
| MDN warns against heavy operations on localStorage | large/CPU-heavy data | developer.mozilla.org |
Use localStorage for small, simple, synchronous data: a settings object, a single JSON save blob, feature flags. Switch to IndexedDB when the data is large, structured, binary, or needs async access that won’t stall rendering: level packs, multiple save slots, downloaded asset caches, replay logs. MDN notes that “developers should be cautious when performing operations on sessionStorage or localStorage that involve a significant amount of data or computationally intensive tasks” – because every read and write is synchronous and can block the main thread, which shows up as dropped frames in a game loop. IndexedDB’s transactional, asynchronous API avoids that.
For actual player progress (level state, currency, purchases), don’t manage either storage yourself. The Playgama Bridge Storage module picks the best place to store data per platform, including cloud saves where available, so progress survives device changes without you writing IndexedDB or localStorage code directly.
What this looks like in code
- Small flag:
localStorage.setItem('muted', 'true')– fine, synchronous, same-origin, persists across restarts. - Large or structured save: open an IndexedDB database, create an object store per data type, use transactions for writes, and read asynchronously so the game loop keeps running.
- Engine code calling either API from Unity WebGL goes through a .jslib plugin; from Godot 4 web exports, through the JavaScriptBridge singleton.
Either way, treat missing keys as “no data yet” rather than an error, and load before gameplay starts so defaults apply cleanly.
Sources
- MDN: Web Storage API
- Unity manual: interacting with browser scripting
- Godot docs: exporting for the Web
- Playgama Bridge docs: Storage
Related questions
Does localStorage survive a browser restart?
Yes. MDN states it persists even when the browser is closed and reopened, and is shared by all documents on the same origin.
Can I store binary data like images in localStorage?
Technically only as strings (e.g. base64), which is inefficient. IndexedDB stores structured and binary data directly and is the better fit.
Should game progress ever be saved only to localStorage?
No – if a game needs cloud saves or cross-device play, saving only to localStorage means that data never reaches the platform’s cloud storage.
Last updated: 24 September 2026