The Storage Landscape: localStorage to OPFS

Your App Needs Memory

Every non-trivial web app stores data on the client. User preferences, auth tokens, cached API responses, offline drafts, entire databases. But here is the thing most developers get wrong: they reach for localStorage every time, like it is the only tool in the box. It is not. The browser gives you at least six distinct storage mechanisms, each with wildly different performance, capacity, and persistence characteristics. Pick the wrong one and you get 5MB hard caps, synchronous main-thread blocking, or data that vanishes after seven days on Safari.

This topic is your map. By the end, you will know exactly which storage API to reach for in every scenario — and more importantly, why.

The Six Storage APIs

1. Cookies

The oldest storage mechanism on the web. Cookies were designed for server communication, not client-side storage. Every cookie is sent with every HTTP request to the matching domain. That alone should tell you they are not for storing application data.

document.cookie = "theme=dark; max-age=31536000; path=/; SameSite=Lax";

const cookies = document.cookie; // "theme=dark; lang=en" — a raw string, not an object

Limits: 4KB per cookie, ~50 cookies per domain (browser-dependent). Total cookie storage is roughly 200KB.

Use for: Authentication tokens (HttpOnly, Secure, SameSite), server-side session IDs, feature flags that the server needs to read on every request.

Never use for: Application state, user preferences, cached data — anything that does not need to travel to the server.

2. Web Storage: localStorage and sessionStorage

The go-to for simple key-value pairs. Both APIs are synchronous and store strings only.

localStorage.setItem("user_prefs", JSON.stringify({ theme: "dark", lang: "en" }));
const prefs = JSON.parse(localStorage.getItem("user_prefs") || "{}");

sessionStorage.setItem("form_draft", JSON.stringify(formData));

localStorage persists until explicitly cleared. sessionStorage is scoped to the browser tab and cleared when the tab closes.

Limits: ~5MB per origin (combined for localStorage and sessionStorage). This is a hard cap — no way to request more.

The synchronous problem: Both APIs block the main thread. On a page with 4MB of localStorage data, getItem can block for several milliseconds — enough to cause jank during a frame.

// This blocks the main thread until the read completes
const data = localStorage.getItem("large_dataset"); // 2MB string → blocks ~3-5ms
JSON.parse(data); // another ~5ms for a large object

Use for: Small, simple preferences (theme, language, sidebar collapsed state). Data under 100KB that you read infrequently.

Never use for: Anything over 1MB, data you read on every frame, structured/queryable data, or anything that needs to work in a Web Worker (localStorage is main-thread only).

3. IndexedDB

The browser's built-in database. IndexedDB stores structured data — objects, arrays, blobs, files, ArrayBuffers — with indexes for fast queries. It is asynchronous, transactional, and available in Workers.

const request = indexedDB.open("myApp", 1);

request.onupgradeneeded = (event) => {
  const db = event.target.result;
  const store = db.createObjectStore("products", { keyPath: "id" });
  store.createIndex("category", "category", { unique: false });
};

request.onsuccess = (event) => {
  const db = event.target.result;
  const tx = db.transaction("products", "readwrite");
  tx.objectStore("products").put({ id: 1, name: "Widget", category: "tools" });
};

Limits: Up to 60% of available disk space in Chrome, up to 50% of free disk space in Firefox (capped at 2GB per origin), and up to 60% of total disk in Safari (with a caveat — Safari evicts data after 7 days of no user interaction when ITP is enabled).

Use for: Offline data, cached API responses, large datasets, anything structured that you need to query. This is your default for anything beyond simple preferences.

4. Cache API

Designed specifically for caching HTTP request/response pairs. Tied tightly to service workers, but also available on the main thread.

const cache = await caches.open("api-v1");
await cache.put("/api/products", new Response(JSON.stringify(products)));

const cached = await cache.match("/api/products");
const data = await cached.json();

Limits: Shares the same quota as IndexedDB (they draw from the same storage pool under the Storage API).

Use for: Offline-first network strategies (cache-first, stale-while-revalidate), precaching app shell resources, caching API responses for offline access.

Never use for: Arbitrary key-value storage (use IndexedDB), or anything that is not conceptually an HTTP request/response pair.

5. Origin Private File System (OPFS)

The newest and fastest storage API. OPFS gives you a private, sandboxed file system scoped to your origin. The user cannot see these files in their file explorer. The killer feature: synchronous, high-performance file access in Web Workers via createSyncAccessHandle.

const root = await navigator.storage.getDirectory();
const fileHandle = await root.getFileHandle("data.bin", { create: true });

// In a Worker — synchronous access, no async overhead
const accessHandle = await fileHandle.createSyncAccessHandle();
const buffer = new ArrayBuffer(1024);
accessHandle.read(buffer, { at: 0 });
accessHandle.write(new Uint8Array([1, 2, 3]), { at: 0 });
accessHandle.flush();
accessHandle.close();

Limits: Same quota pool as IndexedDB and Cache API. Performance is 3-4x faster than IndexedDB for large binary operations.

Browser support: Available in Chrome 102+, Firefox 111+, Safari 15.2+ (with full support including createSyncAccessHandle in Safari 17.4+, shipped March 2024).

Use for: SQLite-in-the-browser (via WASM), large binary file processing, high-performance data access in Workers, any scenario where IndexedDB's async transaction overhead is a bottleneck.

6. Cookies vs Web Storage vs IndexedDB vs Cache API vs OPFS

Storage Quotas and Eviction

All modern browsers implement the Storage API specification for managing quotas. IndexedDB, Cache API, and OPFS all draw from the same storage pool.

const estimate = await navigator.storage.estimate();
console.log(`Used: ${(estimate.usage / 1024 / 1024).toFixed(1)} MB`);
console.log(`Quota: ${(estimate.quota / 1024 / 1024).toFixed(1)} MB`);
console.log(`Remaining: ${((estimate.quota - estimate.usage) / 1024 / 1024).toFixed(1)} MB`);

Quota Limits by Browser

Persistent Storage

By default, browser storage is "best effort" — the browser can evict it under storage pressure. You can request persistent storage to opt out of automatic eviction:

const isPersisted = await navigator.storage.persisted();
if (!isPersisted) {
  const granted = await navigator.storage.persist();
  console.log(`Persistent storage ${granted ? "granted" : "denied"}`);
}

Chrome grants persistent storage automatically if the site is bookmarked, has high engagement, or has push notification permission. Firefox shows a permission prompt. Safari does not support the persist() API.

The Decision Tree

When choosing a storage API, ask these questions in order:

1. Does the server need this data on every request? → Cookie (but keep it tiny)
2. Is it a simple preference under 1KB? → localStorage
3. Is it an HTTP response you want to cache for offline? → Cache API
4. Is it structured data you need to query? → IndexedDB
5. Is it large binary data or do you need synchronous Worker access? → OPFS
6. Do you need a full relational database with SQL? → SQLite compiled to WASM, backed by OPFS

Production Scenario: Choosing Storage for a Note-Taking PWA

You are building a note-taking app that works offline. Notes contain text (up to 100KB each), images (up to 5MB each), and metadata (tags, timestamps). Users have up to 10,000 notes. Here is how you split the storage:

Challenge: Storage API Selection

// You are architecting storage for a music streaming PWA.
// Requirements:
// 1. Users can download songs (3-10MB each, up to 500 songs)
// 2. Playlist metadata (names, song order, cover art URLs)
// 3. Playback position for resume (current song, timestamp)
// 4. User's EQ settings (bass, treble, balance — 3 numbers)
// 5. Offline playback must work without network
// 6. App must work on Safari iOS
//
// For each requirement, pick the best storage API and explain why.
// Consider Safari's ITP 7-day eviction and total storage quota.

Key Rules