Cache API vs IndexedDB vs localStorage

Choosing the right storage mechanism

The browser offers three main client-side storage APIs for persistent data. They serve different purposes and complement each other — the key is picking the right one for each use case.

Storage	Best for	Data type	Async?	Approximate size
Cache API	HTTP responses, static assets	Request/Response	Yes	Large (GBs possible)
IndexedDB	Structured app data, offline records	JS objects, blobs	Yes	Large (GBs possible)
localStorage	Tiny config strings, UI preferences	String only	No (synchronous)	~5 MB

Cache API

The Cache API stores Request/Response pairs. It is shaped like HTTP — the key is a URL (or Request object) and the value is a Response. This makes it ideal for:

• Pre-caching static assets (HTML, CSS, JS, images) for offline use
• Runtime caching of API responses inside a Service Worker
• Serving stale content while a fresh version is fetched in the background

The Cache API is most useful in combination with a Service Worker. See the PWA course for Service Worker caching patterns.

IndexedDB

IndexedDB stores arbitrary JavaScript values (objects, arrays, blobs, typed arrays) in object stores with optional indexes. It is the right choice for:

• Offline app data: user records, messages, documents
• Large blobs: audio, video, images that are part of the app’s data model
• Data that needs to be queried, sorted, or filtered client-side
• Any structured data that does not fit the URL-keyed HTTP model

localStorage

localStorage stores string key/value pairs synchronously. It blocks the main thread on every read and write. Despite its convenience, it is only suitable for:

• Tiny preferences: theme choice, language, a single token
• Values read on every page load where the synchronous access is acceptable
• Anything under a few kilobytes

Never store large objects or do frequent writes in localStorage — it will stall rendering.

Decision diagram

flowchart TD
  Q[What do you need to store?]
  Q --> A{HTTP responses
or assets?}
  A -->|Yes| CacheAPI[Cache API
caches.open / put / match]
  A -->|No| B{Structured
app data?}
  B -->|Yes| IDB[IndexedDB
object stores + indexes]
  B -->|No| C{Tiny string
preference?}
  C -->|Yes| LS[localStorage
setItem / getItem]
  C -->|No| IDB

Storage decision: HTTP responses → Cache API, structured data → IndexedDB, tiny strings → localStorage

🗄️ Key point

Use the Cache API for anything that looks like an HTTP response (URL + headers + body). Use IndexedDB for application records and blobs that need to be queried or updated. Use localStorage only for lightweight string preferences that must be read synchronously at startup. For PWA offline strategies, Cache API and IndexedDB often work together — assets in Cache API, app data in IndexedDB.

Trade-offs

Choice	Benefit	Cost
Cache API for HTTP responses	Matches the Request/Response model directly — good fit for pre-cached assets and API responses	Not a good fit for structured data — use IndexedDB instead when you need to query or index it
IndexedDB for app data	Query, index, and transaction support for complex data	Harder API to use — you manage schema versions and object stores yourself
localStorage for small preferences	Simple to read and write, synchronous syntax	Blocks the main thread on every access — unsuitable for large data or frequent writes

Common mistakes

• Using the Cache API to store plain JS objects by JSON-stringifying them into a Response yourself — unnecessary complexity; if the data isn’t an HTTP request/response, reach for IndexedDB from the start.
• Using localStorage for large data or an entire cache — localStorage’s synchronous I/O blocks the main thread and stalls the UI; move it to IndexedDB or the Cache API.
• Assuming the Cache API and IndexedDB compete and you must pick one — most PWAs use both together: Cache API for assets, IndexedDB for app data.

🗄️ Real-world example

Twitter Lite (PWA) — used the Cache API to store its app shell (HTML/CSS/JS) for fast loads, and IndexedDB to store timeline data and user records that needed to be queried. Source: web.dev case study, “Twitter Lite PWA significantly increases engagement and reduces data usage”.

Which storage API is purpose-built for caching HTTP responses and static assets?

Cache API IndexedDB localStorage sessionStorage

Which storage API blocks the main thread on every read and write?

Cache API IndexedDB localStorage All three block the main thread

You need to store a large array of user messages for offline access, with the ability to query by date. Which API should you use?

localStorage — it is the simplest API IndexedDB — it supports structured data and indexes Cache API — it supports large data sessionStorage — it is more reliable than localStorage

Which storage API would you choose to cache JS and CSS bundles for a PWA that must work offline?

Cache API with a Service Worker IndexedDB localStorage sessionStorage

Submit

Mark as complete