Cookies, localStorage, sessionStorage

Why you need storage in the browser

HTTP is stateless: the server doesn't know that request 2 comes from the same person as request 1. And a page starts from scratch on every reload. To "remember" anything — login, cart, preferences, a half-filled form — you need a place where data survives.

The browser gives you 5 such places, each with a different purpose.

Storage types compared

All of them are isolated per origin: a.com can't read what b.com saved.

Cookies

A cookie is a small piece of text the server sets, and the browser sends back automatically on every request to the same site. That's why it's the only way the server can recognize you.

Set-Cookie: session=abc123; Max-Age=2592000; Path=/; HttpOnly; Secure; SameSite=Lax

This app sets a vid cookie (httpOnly) — that's how it recognizes your progress on the server without an account.

In Next you read cookies with cookies() from next/headers and set them in Server Actions, Route Handlers or proxy.ts.

localStorage

Key → string storage, permanent, shared by all tabs of the same site.

localStorage.setItem('theme', 'dark')
localStorage.getItem('theme')                 // 'dark'
localStorage.removeItem('theme')

localStorage.setItem('cart', JSON.stringify(cart))   // objects → JSON
const cart = JSON.parse(localStorage.getItem('cart') ?? '[]')

• Strings only — objects go through JSON.stringify / JSON.parse.
• Synchronous API: it blocks the thread; don't save megabytes on every keystroke.
• When one tab changes localStorage, the other tabs receive a storage event — that's how you sync the theme across tabs.

sessionStorage

The same API as localStorage, but data lives only as long as the tab:

sessionStorage.setItem('checkout-step', '2')
sessionStorage.getItem('checkout-step')       // '2' — only in this tab

When it beats localStorage: a checkout wizard or a long form open in two tabs — each tab keeps its own progress without stepping on the other.

IndexedDB

A database in the browser: tables (object stores), indexes, transactions, whole objects (not just strings), files. The API is asynchronous (doesn't block the page) but verbose — in practice you use a small wrapper:

import { get, set } from 'idb-keyval'
await set('drafts', [{ id: 1, text: '...' }])   // objects directly, no JSON
const drafts = await get('drafts')

For: offline apps, large data caches, user files before upload.

Cache Storage

Stores whole request → response pairs. Service workers use it to make a site work offline (PWA). You rarely touch it directly in regular apps.

Safety rules

• Never put auth tokens in localStorage / sessionStorage — any script on the page (including one injected through XSS) can read them. The session lives in an HttpOnly cookie.
• Storage can throw (private mode, quota exceeded, site data blocked) → wrap every read / write in try/catch.
• It doesn't exist on the server: in Next, read it only in Client Components after mounting (in useEffect or useSyncExternalStore), otherwise you get hydration errors.
• The user can clear it at any time — it's not a reliable database for important data.

How to choose

Summary

• A cookie is the only one sent to the server automatically; HttpOnly; Secure; SameSite=Lax for sessions.
• localStorage = permanent, all tabs; sessionStorage = per tab, until closed; both strings only, synchronous.
• IndexedDB for large and offline data; never secrets in storage; always try/catch.

Official sources

• MDN — Using HTTP cookies
• MDN — Web Storage API
• MDN — Window.sessionStorage
• MDN — IndexedDB API
• MDN — CacheStorage