Cache API & file storage

Responses, quota, and private files

Browser storage is not one toolbox. It is a set of very different tools. The Cache API stores whole Request → Response pairs. The Storage Manager tells you roughly how much space your origin is using and whether it has persistent storage. The Origin Private File System, usually shortened to OPFS, gives your site private file and folder handles.

Those APIs are useful when an app should feel fast or keep working offline: documentation readers, drawing tools, recipe apps, music editors, dashboards, and installable web apps. They are also easy to misuse if you treat all storage as “a place to put stuff.” In this lesson we choose storage by the shape of the data and the lifetime you need.

Definition: CacheStorage is the browser’s collection of named Cache objects; each Cache maps requests to responses. OPFS is a private file area for the same origin. Quota is the browser’s estimate of how much room that origin may use.

The global caches object is a CacheStorage. It is available in windows and workers in supporting secure contexts; http://localhost counts as secure for development. You call caches.open(name) to get a named Cache, then use methods such as put, add, match, keys, and delete.

1const cache = await caches.open("cf-demo-pantry");2await cache.put(3  "/cf-demo/menu.json",4  new Response(JSON.stringify(menu), {5    headers: { "Content-Type": "application/json", "X-Saved-At": savedAt },6  }),7);8await cache.add(location.href);9const match = await cache.match("/cf-demo/menu.json?from=button", { ignoreSearch: true });10const allKeys = await cache.keys();11await cache.delete("/cf-demo/menu.json");

The value is a real Response. Headers come with it. Bodies are streams, so if you fetched a response and also want to read it in your code, clone it before one copy is consumed. Opaque responses can be cached too, but scripts cannot inspect their contents and browsers may charge padded quota space for privacy.

This playground uses the real Cache API when your browser exposes caches. It creates a demo cache named cf-demo-pantry, stores a synthetic JSON response, stores this same-origin page with cache.add(location.href), matches with ignoreSearch, lists keys, proves caches.match searches across named caches, and deletes the demo data.

1const cache = await caches.open("cf-demo-pantry");2await cache.put(3  "/cf-demo/menu.json",4  new Response(JSON.stringify(menu), {5    headers: { "Content-Type": "application/json", "X-Saved-At": savedAt },6  }),7);8await cache.add(location.href);9const match = await cache.match("/cf-demo/menu.json?from=button", { ignoreSearch: true });10const allKeys = await cache.keys();11await cache.delete("/cf-demo/menu.json");

Reset deletes the demo cache. The component also deletes it on unmount. That cleanup matters: educational demos should not leave mystery storage behind.

Service workers often pair the Cache API with request strategies. You can use the same ideas in app code: try the cache first, fall back to the network, or serve something cached while refreshing it for the next visit.

1async function getMenu(cache, network, mode) {2  const cached = cache.match("/menu.json");3 4  if (cached && mode === "cache-first") {5    return { source: "cache", menu: cached.menu };6  }7 8  if (cached && mode === "stale-while-revalidate") {9    network.fetch("/menu.json").then((fresh) => {10      cache.put("/menu.json", fresh);11    });12    return { source: "cache", menu: cached.menu };13  }14 15  const fresh = await network.fetch("/menu.json");16  cache.put("/menu.json", fresh);17  return { source: "network", menu: fresh.menu };18}

1async function getMenu(cache, network, mode) {Run2  const cached = cache.match("/menu.json");3 4  if (cached && mode === "cache-first") {5    return { source: "cache", menu: cached.menu };6  }7 8  if (cached && mode === "stale-while-revalidate") {9    network.fetch("/menu.json").then((fresh) => {10      cache.put("/menu.json", fresh);11    });12    return { source: "cache", menu: cached.menu };13  }14 15  const fresh = await network.fetch("/menu.json");16  cache.put("/menu.json", fresh);17  return { source: "network", menu: fresh.menu };18}

Cache-first is great for versioned files and app shells where cached is usually correct. Stale-while-revalidate is great when speed matters and yesterday’s data is acceptable for a moment. It is a poor fit for bank balances, checkout prices, or anything where old data can harm the user.

navigator.storage.estimate() returns approximate usage and quota. Some browsers include usageDetails. navigator.storage.persisted() reports whether the origin is already persistent, and persist() asks for persistence. Depending on the browser, that request may be granted automatically, prompt the user, or be denied.

1const estimate = await navigator.storage.estimate();2const persisted = await navigator.storage.persisted();3// Only ask after a user click; some browsers prompt here.4const granted = await navigator.storage.persist();

1const estimate = await navigator.storage.estimate();2const persisted = await navigator.storage.persisted();3// Only ask after a user click; some browsers prompt here.4const granted = await navigator.storage.persist();

Persistence reduces automatic eviction under storage pressure; it is not a backup system. Users can still clear site data, private browsing can be temporary, and your app should rebuild caches when needed.

The entry point is navigator.storage.getDirectory(), which returns the OPFS root FileSystemDirectoryHandle. In supporting browsers you can create a file, call createWritable(), write text or bytes, close the stream, read with getFile().text(), iterate entries, and delete with removeEntry. Sync access handles are for dedicated workers; this page demonstrates the main-thread writable flow only when available.

1const root = await navigator.storage.getDirectory();2const demo = await root.getDirectoryHandle("cf-demo", { create: true });3const file = await demo.getFileHandle("menu-note.txt", { create: true });4const writable = await file.createWritable();5await writable.write("Cache pantry inspected at lunch.");6await writable.close();7const text = await (await file.getFile()).text();8for await (const [name, handle] of demo.entries()) {9  console.log(name, handle.kind);10}11await root.removeEntry("cf-demo", { recursive: true });

1const root = await navigator.storage.getDirectory();2const demo = await root.getDirectoryHandle("cf-demo", { create: true });3const file = await demo.getFileHandle("menu-note.txt", { create: true });4const writable = await file.createWritable();5await writable.write("Cache pantry inspected at lunch.");6await writable.close();7const text = await (await file.getFile()).text();8for await (const [name, handle] of demo.entries()) {9  console.log(name, handle.kind);10}11await root.removeEntry("cf-demo", { recursive: true });

The fastest way to choose is to ask what shape the data has. Is it a response? A private file? A tiny string preference? A queryable collection? A credential JavaScript should not read?

1function chooseStorage(need) {2  if (need === "offline app shell") return "Cache API";3  if (need === "large private file") return "OPFS or IndexedDB";4  if (need === "small UI preference") return "localStorage";5  if (need === "queryable records") return "IndexedDB";6  return "HttpOnly cookie";7}

Imagine a restaurant menu editor. The public app caches the menu JSON and shell files so repeat visitors see the menu instantly. The editor estimates quota before saving large image drafts. Draft notes and generated images live in OPFS under a project folder. The user’s theme choice is just a tiny localStorage value. Their login token belongs in an HttpOnly cookie, not in script-readable storage.

Professional code also includes cleanup. Name caches with versions, remove old versions, cap large OPFS projects, and rebuild derived caches if they disappear. Treat browser storage as helpful local state, not your only copy of critical user data.

• “The Cache API is the HTTP cache.” They are separate. Your code manages named Cache objects.
• “Cache API entries expire by themselves.” They do not. Use versions and cleanup.
• “A cached Response can be read forever.” Stored responses can be matched again, but each Response body stream you hold is still one-use. Clone before two reads.
• “Quota is guaranteed storage.” It is approximate and can change. Non-persistent data may be evicted.
• “persist() always shows a permission prompt.” Browsers vary: automatic grant, prompt, or denial are all possible.
• “OPFS files show up in the user’s file browser.” They are private to the origin and are removed with site data.

Key takeaways

• The Cache API stores named Request → Response pairs and does not expire them automatically.
• Clone responses before caching and reading when two consumers need the same body.
• navigator.storage.estimate() reports approximate usage and quota; persist() asks for reduced eviction risk.
• OPFS gives private origin files and folders through handles, with browser support and cleanup responsibilities to check.
• Choose storage by data shape: responses, files, tiny preferences, records, or credentials.

Final definition: Cache API stores replayable responses, Storage Manager describes the origin’s space, and OPFS stores private files for apps that need file-shaped data.

Up next: Observers — React to visibility, DOM, and size changes efficiently.