termEngineering & architecture

Web Storage

Web Storage provides origin-scoped localStorage and sessionStorage key-value stores that browser scripts access synchronously.

Download Markdown (.md)

01What it means

Web Storage is the browser API exposing localStorage and sessionStorage as string key-value stores. localStorage persists for an origin across browser sessions subject to user controls, while sessionStorage is separated by origin and top-level browsing context and lasts for the page session. It is distinct from cookies, IndexedDB, Cache Storage, and the broader Storage API.[1][2]

02Why it matters

Web Storage is simple for small preferences or transient state, but synchronous access can block the main thread and stored values are available to scripts running in the origin. Scope, lifetime, privacy, and failure behavior affect product correctness.

03When to use it

Use it for small, non-sensitive strings such as a dismissed hint or local display preference. Use IndexedDB for larger structured data, cookies only when data must accompany HTTP requests, and server storage for authoritative cross-device state.

04How it works

  1. Choose localStorage or sessionStorage according to the required scope and lifetime.
  2. Serialize the minimal string value and write it under a stable key.
  3. Read defensively because values may be absent, stale, malformed, or unavailable.
  4. Handle storage events when same-origin documents must notice localStorage changes.
  5. Version and remove obsolete keys while respecting consent and reset behavior.

05A practical example

Example

A documentation site stores a user's preferred code language in localStorage. The server still returns a usable default, the client validates the stored value, and a settings action lets the user reset it.

06Where it breaks

Operations are synchronous, capacity is limited and browser-dependent, users or browsers can clear data, and storage may be partitioned. Any script executing in the origin can potentially read values, so it is not a safe place for secrets.

Common mistakes

  • Storing access tokens or sensitive personal data because the store feels local.
  • Confusing localStorage persistence with guaranteed durable storage.
  • Writing large structured datasets on the main thread.
  • Assuming sessionStorage is shared normally across all tabs.

07Sources

  1. Web Storage APIMDN Web Docs · Official technical documentationWeb Storage API
  2. HTML Standard: Web StorageWHATWG · Living web standardHTML Standard: Web Storage
View saved topics

Start typing to search titles, definitions, categories, and frameworks.