Cache HTTP responses at the edge with the Cache API

Not every response needs a fresh origin fetch. The Workers Cache API (caches.default) lets you store Response objects at the edge with explicit cache keys - perfect for expensive GETs that are safe to reuse.

The Edge Cache experiment demonstrates HIT/MISS behavior so you can see caching work before wiring it into production routes.

Cloudflare products in this patternCopy Anchor Link

Cache API vs CDN cache vs R2Copy Anchor Link

Use the Cache API when your Worker decides what to cache. Use Cache Rules when the zone can express the policy without custom code. Use R2 when you need durable objects, not a short TTL HTTP cache.

See also: How Cache works on Cloudflare.

Minimal patternCopy Anchor Link

const cache = caches.default;
const cacheKey = new Request(url, { method: "GET" });

let response = await cache.match(cacheKey);
if (response) {
  return new Response(response.body, response);
}

const origin = await fetch(url);
response = new Response(origin.body, origin);
response.headers.set("Cache-Control", "s-maxage=60");
ctx.waitUntil(cache.put(cacheKey, response.clone()));
return response;

Details and caveats: Cache · Workers. The experiment surfaces HIT/MISS clearly so you can debug keys and TTLs without guessing.

Rules that prevent footgunsCopy Anchor Link

1. Only cache GET (or idempotent reads you fully control)
2. Vary your cache key on anything that changes the body (auth, locale, query)
3. Do not cache personalized private data under a shared key
4. Set explicit TTLs - accidental year-long caches hurt more than MISS latency
5. Purge strategy - know how you will invalidate (purge cache for CDN; key versioning for Cache API)
6. Clone responses before put/return when bodies are one-shot streams

Pairing with other experimentsCopy Anchor Link

ObservabilityCopy Anchor Link

• Add X-Cache: HIT|MISS response headers in your Worker for browser DevTools
• Log cache key hash + colo from request.cf
• Alert on sudden MISS storms after deploys (often key-format changes)

Deploy Edge CacheCopy Anchor Link

1. Read Workers Cache API
2. Open Edge Cache
3. Deploy and call the same URL twice
4. Confirm HIT on the second request
5. Change the cache key inputs and watch MISS return
6. Port the helper into your proxy or API Worker
7. Use Cache Rules for pure static assets at the zone when code is unnecessary

Caching is one of the highest-leverage edge features - this experiment makes HIT/MISS observable so you can ship it with confidence on Cloudflare’s Cache API.

Production checklistCopy Anchor Link

1. Cache only safe GETs.
2. Include every body-affecting input in the cache key.
3. Set explicit TTLs.
4. Add X-Cache: HIT|MISS for debugging.
5. Prefer Cache Rules for static zone assets.
6. Use R2 for durable artifacts, Cache API for short TTL HTTP responses.

FAQCopy Anchor Link

Why am I always missing?Copy Anchor Link

Key mismatch after deploys is the usual culprit - log the key hash. Also confirm you clone() before put.