Browser storage: what lives where, and for how long

HOW IT FITS TOGETHER

KEY TERMS

One quota per origin

IndexedDB, Cache API, OPFS and service worker registrations share a single storage bucket per origin (partitioned further by top-level site for third-party iframes). navigator.storage.estimate() returns approximate usage and quota for that bucket; the numbers are deliberately imprecise to limit fingerprinting.

Best-effort vs persistent

Buckets start best-effort: the browser may delete them without telling the user when space runs low. navigator.storage.persist() asks to switch to persistent, which is only cleared by the user. Firefox prompts; Chrome, Edge and Safari decide silently from signals such as engagement and installation.

Eviction

When the browser hits its overall limit or the device runs low, it deletes whole origins, least recently used first, skipping persistent ones. You never lose half an origin's data from eviction, but you can lose IndexedDB, caches and the service worker together.

Safari's 7-day cap

With tracking prevention on, Safari deletes all script-writable storage (IndexedDB, localStorage, sessionStorage, service worker registrations and caches) after seven days of Safari use with no user interaction on the site. Server-set cookies are exempt; cookies written by document.cookie are capped at a 7-day expiry. Home Screen web apps have their own days-of-use counter.

Cookie attributes

HttpOnly hides a cookie from JavaScript; Secure limits it to HTTPS; SameSite=Lax (the default when unset in browsers that implement it) withholds it from cross-site subrequests; SameSite=None requires Secure. The __Host- prefix requires Secure, Path=/ and no Domain. Partitioned (CHIPS) keys a third-party cookie to the top-level site; it is Baseline since December 2025.

OPFS

The Origin Private File System is a sandboxed file tree from navigator.storage.getDirectory(). In a dedicated worker, createSyncAccessHandle() gives exclusive, synchronous read/write/flush on a file, which is what SQLite-in-WASM builds use. Users cannot see these files.

Private browsing and Storage Buckets

Private modes give separate, often smaller quotas and delete everything when the session ends. Storage Buckets (navigator.storageBuckets.open, Chromium 122+) let one origin create several independently evictable buckets with their own persistence and durability; Chromium currently supports only IndexedDB in them, so feature-detect before relying on it.

IN YOUR STACK

export function createStore<T>(key: string, version: number, fallback: T) {
  return {
    get(): T {
      try {
        const raw = localStorage.getItem(key);
        if (raw === null) return fallback;
        const parsed = JSON.parse(raw) as { v: number; data: T };
        return parsed.v === version ? parsed.data : fallback; // ignore old shapes
      } catch {
        return fallback; // corrupt JSON, or storage blocked (SecurityError)
      }
    },
    set(data: T): boolean {
      try {
        localStorage.setItem(key, JSON.stringify({ v: version, data }));
        return true;
      } catch (err) {
        if (err instanceof DOMException && err.name === "QuotaExceededError") return false;
        throw err;
      }
    },
  };
}
const prefs = createStore("prefs", 2, { theme: "system" });
addEventListener("storage", (e) => { if (e.key === "prefs") document.documentElement.dataset.theme = prefs.get().theme; });

import { openDB, type DBSchema } from "idb";
interface AppDB extends DBSchema {
  outbox: { key: string; value: { id: string; body: unknown; createdAt: number }; indexes: { byCreatedAt: number } };
}
const dbPromise = openDB<AppDB>("app", 2, {
  upgrade(db, oldVersion, _newVersion, tx) {
    if (oldVersion < 1) db.createObjectStore("outbox", { keyPath: "id" });
    if (oldVersion < 2) tx.objectStore("outbox").createIndex("byCreatedAt", "createdAt");
  },
  blocking() { void dbPromise.then((db) => db.close()); }, // let another tab upgrade
});
export async function enqueue(body: unknown) {
  const db = await dbPromise;
  await db.put("outbox", { id: crypto.randomUUID(), body, createdAt: Date.now() });
}
export async function drain(send: (body: unknown) => Promise<void>) {
  const db = await dbPromise;
  for (const item of await db.getAllFromIndex("outbox", "byCreatedAt")) {
    await send(item.body); // network call outside any transaction
    await db.delete("outbox", item.id);
  }
}

const CACHE = "avatars-v1";

export async function cachedFetch(url, maxAgeMs = 60 * 60 * 1000) {
  const cache = await caches.open(CACHE);
  const hit = await cache.match(url);
  const age = hit ? Date.now() - Number(hit.headers.get("x-cached-at")) : Infinity;
  if (hit && age < maxAgeMs) return hit;

  const response = await fetch(url);
  if (!response.ok) return hit ?? response; // serve stale rather than fail
  const headers = new Headers(response.headers);
  headers.set("x-cached-at", String(Date.now())); // Cache API has no expiry of its own
  const body = await response.blob();
  await cache.put(url, new Response(body, { status: response.status, headers }));
  return new Response(body, { status: response.status, headers });
}

export async function dropOldCaches() {
  for (const name of await caches.keys()) {
    if (name !== CACHE) await caches.delete(name);
  }
}

// main.js
const worker = new Worker(new URL("./log.worker.js", import.meta.url), { type: "module" });
worker.postMessage({ name: "events.ndjson", line: JSON.stringify({ at: Date.now(), type: "open" }) });

// log.worker.js: sync access handles exist only in dedicated workers
const handles = new Map();
const encoder = new TextEncoder();

function handleFor(name) {
  if (!handles.has(name)) {
    handles.set(name, navigator.storage.getDirectory()
      .then((root) => root.getFileHandle(name, { create: true }))
      .then((file) => file.createSyncAccessHandle())); // exclusive lock on the file
  }
  return handles.get(name);
}

self.onmessage = async ({ data: { name, line } }) => {
  const access = await handleFor(name);
  access.write(encoder.encode(line + "\n"), { at: access.getSize() }); // synchronous
  access.flush();
};

export async function storageReport() {
  if (!navigator.storage?.estimate) return null;
  const { usage = 0, quota = 0 } = await navigator.storage.estimate();
  return {
    usedMB: Math.round(usage / 1e6),
    quotaMB: Math.round(quota / 1e6),
    percent: quota ? Number(((100 * usage) / quota).toFixed(1)) : 0,
    persisted: await navigator.storage.persisted(),
  };
}

// Ask during a meaningful action ("Save for offline"), never on page load.
export async function requestDurableStorage() {
  if (await navigator.storage.persisted()) return true;
  const granted = await navigator.storage.persist(); // Firefox prompts; others decide silently
  if (!granted) console.info("best-effort: data may be evicted under storage pressure");
  return granted;
}

document.querySelector("#save-offline")?.addEventListener("click", async () => {
  await requestDurableStorage();
  console.table(await storageReport());
});

# Session: hidden from JS, HTTPS only, host-locked, sent on top-level navigations
Set-Cookie: __Host-session=9f2c41e7; Path=/; Secure; HttpOnly; SameSite=Lax; Max-Age=1209600

# CSRF token the page must read: no HttpOnly, never sent cross-site
Set-Cookie: __Host-csrf=b81e09aa; Path=/; Secure; SameSite=Strict; Max-Age=7200

# Third-party iframe widget: one cookie jar per top-level site (CHIPS)
Set-Cookie: __Host-widget=34d8g; Path=/; Secure; HttpOnly; SameSite=None; Partitioned

# Logout: same name, path and attributes, expired
Set-Cookie: __Host-session=; Path=/; Secure; HttpOnly; SameSite=Lax; Max-Age=0

WHEN TO REACH FOR WHAT

WHERE IT BITES

• Assuming local data is permanent. Eviction, Safari's 7-day cap and "clear site data" all delete it; the server or a re-sync must be able to rebuild state.
• Keeping auth tokens in localStorage. Any injected script can read and exfiltrate them; HttpOnly cookies cannot be read by script.
• Large or frequent localStorage writes on the main thread. They are synchronous and show up as input lag on slower devices.
• Awaiting a fetch inside an IndexedDB transaction. The transaction auto-commits and the next request throws TransactionInactiveError.
• Not handling QuotaExceededError. Quotas vary by browser, device and mode, and private browsing can be far smaller than you test with.
• Testing only in a regular Chrome profile. Safari's ITP, installed web apps, Firefox's prompt and private modes all behave differently.

WHEN IT BREAKS IN PRODUCTION

• Offline edits conflict or vanish on reconnect

SOURCES

• MDN: Storage quotas and eviction criteria (opens in new tab)Checked 2026-10-11
• WebKit: Updates to Storage Policy (opens in new tab)Checked 2026-10-11
• WebKit: Full Third-Party Cookie Blocking and More (opens in new tab)Checked 2026-10-11
• web.dev: Persistent storage (opens in new tab)Checked 2026-10-11
• Chrome for Developers: Storage Buckets (opens in new tab)Checked 2026-10-11
• MDN: Partitioned cookies (CHIPS) (opens in new tab)Checked 2026-10-11