Lesson 0001 · ~10 minutes

When Cache API fits (and when it doesn’t)

One skill: place Cache Storage on the client storage spectrum and pick it only when the hard problem is durable HTTP Request/Response resources (app shell, assets, offline-capable fetches).

Glossary Resources Mission

Win for this lesson

After the quiz, you can defend “Cache API yes / no” in a design review without writing a line of caches.open yet — and without confusing it with IndexedDB or the browser’s HTTP cache.

1. The problem Cache Storage solves

Network can be slow, flaky, or offline. Even when it’s fine, re-downloading the same HTML/JS/CSS/images on every visit wastes time and bandwidth. Users expect a shell that still appears when connectivity is gone.

The Cache / CacheStorage APIs are the browser’s main answer for code-driven storage of network resources: pairs of Request / Response objects you open, fill, match, and delete yourself. web.dev ’s default split is blunt: for the network resources needed to load your app, use the Cache Storage API; for other app data, prefer IndexedDB (and OPFS for file-shaped content).

The API was built so service workers can answer fetches offline or faster — but it is also available from windows and other workers via the global caches object (Cache API quick guide).

2. Not IndexedDB, and not “just Cache-Control”

Two common confusions:

Not a general database. Cache Storage only stores Request/Response pairs. There are no object stores, secondary indexes, or “query all drafts by author.” Filtering by iterating cache.keys() is possible but clumsy for large entity sets — that’s why IndexedDB exists for structured app data (quick guide even points at IDB when you need a searchable index).
Not the HTTP cache. The browser’s HTTP cache is driven by headers and heuristics. Cache Storage is code-driven: nothing expires unless you delete or replace it; nothing enters unless you add/put it (MDN Cache, SW + Cache Storage). The two layers can cooperate — or fight — when a service worker is involved.

Mental model: Cache Storage is a named warehouse of HTTP-shaped resources you manage. A service worker is often the warehouse manager on the fetch path; strategies (cache-first, network-first, …) come later.

3. The client storage spectrum (Cache API highlighted)

Same map you used in the IndexedDB track — steal again from Storage for the web. Today the spotlight is the Cache Storage row.

Memory only

React/Vue state, module variables. Fastest. Dies on refresh. Fine when re-fetch or re-derive is cheap.

sessionStorage

Tab-scoped string map; survives reloads in that tab, not other tabs. Sync API; tiny; not for workers. Prefer sparingly.

localStorage

Origin-scoped string map that persists. Sync on main thread; ~few MB; no workers. Avoid for bulk or hot-path structured data.

Tiny values often sent on every HTTP request. Session/auth use-cases only — not a general client database or asset store.

IndexedDB

Large structured app data: drafts, entity caches, offline queues, user-generated records. Async; keys + indexes; works off-main-thread.

Cache API

Request/Response pairs — HTML/JS/CSS/images and other HTTP resources for load/offline shells and runtime resource caching.

OPFS

File-shaped bytes on an origin-private filesystem. Editors, media pipelines, “this is a file” models — not the first stop for HTTP shells or keyed records.

Default rule (steal this)

If the hard part is “make the app shell and static (or versioned) assets load when the network is bad or gone”, start with Cache Storage — usually behind a service worker. If the hard part is “persist structured application data so we can show or edit it without a round trip”, that is IndexedDB. If the hard part is “tiny string flag”, Web Storage may be enough. If the hard part is “truth lives on the server and re-fetch is fine”, prefer no durable client store — and don’t invent a cache strategy for sport.

Signal	Leans Cache Storage	Leans away
Shape	HTTP assets; Request → Response	Objects, drafts, queues, entity graphs
Job	Load shell offline; speed repeat visits	Query/filter app records by field
Control	You own put/match/delete and versions	Only need header-based browser caching
Classic fits	Offline `app.js` shell, font/CSS bundles, image runtime cache, precached routes	Multi-paragraph drafts, CRM contact rows, theme toggle string, video editor file buffer

FE integration difficulty (honest preview)

Opening a named cache is not the hard part. What bites teams later: versioning and cleanup (old named caches left forever), stale content (nothing auto-expires), opaque responses and CORS edge cases, HTTP cache vs SW cache interaction, and quota / eviction (especially Safari policies). We’ll drill those later. Today only know they exist so you don’t oversell “just cache everything.”

4. Practice — pick the store

Choose the best default. Equal-length options so formatting doesn’t hint. Feedback is immediate.

Scenario A

PWA shell: HTML, CSS, and JS must load so the UI appears when the network is completely gone.

Scenario B

Writing app: multi-paragraph drafts must survive refresh and work offline until the user hits Publish.

Scenario C

Settings: remember light/dark theme across visits. One string; slightly delayed apply is fine.

Scenario D

Marketing site: fingerprint-hashed JS/CSS bundles should load fast on repeat visits and still work offline for returning users.

Scenario E

Internal admin: always online; table of 20 rows from REST; no offline requirement; refresh is acceptable.

5. What to remember

Cache Storage = async, origin-scoped Request/Response warehouse — code-driven; you own updates and deletes.
Steal the web.dev split: Cache API for load/network resources, OPFS for file-shaped content, IndexedDB for other app data.
Distinct from the browser HTTP cache (headers/heuristics) even though both “cache.”
Integration pain is usually versioning, stale content, opaque/CORS cases, dual-cache interaction, and quotas — not the first open call.

Ask your teacher Anything fuzzy — “isn’t this just Service Workers?”, a feature on your team, how this maps to Workbox — ask in chat. Follow-up questions are part of the method, not a distraction.

Primary source (read next)

web.dev — Storage for the web (Pete LePage et al.). Best short primary for this lesson’s spectrum and defaults (Cache Storage vs IndexedDB vs OPFS). Then skim The Cache API: a quick guide so the next lesson’s method map isn’t new twice.