Workers Cache: Your Cloudflare Worker Finally Has a Cache in Front

The core idea

Cloudflare just launched Workers Cache. It is a tiered cache that sits directly in front of your Worker entrypoints, and it changes the mental model of building on the edge.

Before this, Cloudflare's architecture put the Worker in front of the cache. The Worker ran on every request, transforming traffic on its way to an origin. That made sense in 2017 when Workers were middleware bolted onto existing infrastructure. But Workers stopped being middleware years ago. Frameworks like Astro, Next.js, TanStack Start, Remix, and SvelteKit all ship Cloudflare adapters that build your app as a Worker with no origin behind it. The Worker is the server.

Workers Cache flips the architecture. Now the cache sits in front of the Worker. On a cache hit, your Worker does not run. Cloudflare returns the cached response from the nearest of its 330+ locations, and your CPU billing stays at zero. On a miss, your Worker runs once, populates the cache, and the next request from anywhere gets served from cache without invoking your code.

The whole thing is one boolean in wrangler.json:

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-05-01",
  "cache": {
    "enabled": true
  }
}

After that, you control caching the same way HTTP intended: through response headers.

return new Response(body, {
  headers: {
    "Cache-Control": "public, max-age=300, stale-while-revalidate=3600",
    "Cache-Tag": "products,product:123",
  },
});

And when content changes, you purge from your Worker's own code:

await ctx.cache.purge({ tags: ["product:123"] });

No separate cache to provision. No rules engine to configure. No second product to log into. The Worker's code is the configuration surface, and the cache follows the Worker wherever it runs.

How it works

The cache is tiered across Cloudflare's entire network. Each colo has a local L1 cache backed by RAM and NVMe. On a miss, the request goes to the regional L2 cache (the nearest larger data center). Only if both miss does the request reach your Worker. This matters because a tiered cache means the first visitor from Johannesburg and the second from Sao Paulo both get served locally after the first fetch populates the chain.

The cache supports the full HTTP caching toolkit:

• Cache-Control directives you already know: max-age, s-maxage, public, private, no-cache, must-revalidate.
• stale-while-revalidate so stale responses never block a user. Serve the stale copy instantly, revalidate in the background.
• Vary for content negotiation. Serve different cached versions for different Accept headers, languages, or device types.
• Cache-Tag for granular invalidation. Tag responses by entity, purge by tag.
• ctx.cache.purge() by exact URL, path prefix, or tag from within your Worker code.

But the most interesting part is per-entrypoint control. Workers Cache sits in front of every Worker entrypoint, not just the public one. You decide which entrypoints cache and which do not. This means you compose caching into the structure of your app itself.

Where teams mess it up

The biggest mistake will be treating Workers Cache like a magic speed switch. It is not. It is a caching layer, and caching is hard.

First mistake: caching dynamic content that should not be cached. A Worker that returns personalized content based on cookies or auth headers will serve the wrong response to the wrong user unless you handle it. Use Cache-Control: private for user-specific responses, or use Vary with the right headers. Better yet, let authenticated requests bypass the cache entirely by not setting cache headers on those responses.

Second mistake: forgetting to purge. Content changes, and stale data is worse than slow data. Use Cache-Tags and purge by tag when content updates. If you are building a CMS or an e-commerce site, tag every product page by product ID and purge the tag when inventory changes. Do not wait for the TTL to expire.

Third mistake: cache key collisions in multi-tenant Workers. If one Worker serves multiple tenants, ensure your cache keys include tenant identity. The article mentions ctx.props for this exact problem.

Fourth mistake: assuming caching replaces database optimization. Workers Cache prevents your Worker from running on cache hits. That is huge. But on a cache miss, your Worker still needs to be fast. Do not let caching mask a slow origin data path.

Practical patterns

API response caching. Your public REST or GraphQL API is the obvious candidate. Set Cache-Control: public, max-age=60 on GET endpoints that return stable data. Watch your cache hit ratio climb and your CPU time drop. Use Cache-Tags to segment by resource type so you can invalidate precisely.

SSR page caching. Server-rendered pages from Next.js or Astro running on Workers are the killer use case. Before Workers Cache, every page view ran the full render pipeline. Now a blog post with a 5-minute TTL gets served from cache to 99% of visitors. The first visitor after a publish pays the render cost; everyone else gets an instant response.

Partial caching with entrypoint composition. The per-entrypoint feature lets you chain Workers. Have a public-facing Worker that aggregates data from an internal API Worker. Cache the internal Worker's responses heavily. Only the aggregation logic runs on every request, and the heavy data fetching runs once per TTL.

Stale-while-revalidate for dashboards. A metrics dashboard can serve stale data instantly while revalidating in the background. Set max-age=30, stale-while-revalidate=300. Every user gets sub-millisecond response time, and the data is never more than 5 minutes stale.

Trade-offs

Workers Cache adds a new dimension to your architecture decisions. The benefit is obvious: fewer Worker invocations means lower latency and lower cost. But you now have a cache to manage.

• Cache invalidation is your new job. Every write path needs a corresponding purge call. Miss one, and stale data lingers for the TTL duration.
• Debugging gets harder. A stale response in production can be infuriating to track down. Add CF-Cache-Status header inspection to your debugging toolkit. The header tells you whether a response came from cache (HIT), your Worker (MISS), or was revalidated (STALE/REVALIDATED).
• Cold start costs shift. The first request to a new or freshly-purged endpoint pays the full Worker runtime cost. Under high traffic this amortizes immediately. Under low traffic, caching buys you very little and adds complexity.
• No cache for POST or non-cacheable methods. Workers Cache only caches GET and HEAD requests. Your mutations, webhooks, and form submissions still run every time.

Builder relevance

If you run any server-rendered app on Cloudflare Workers, enable Workers Cache today. It is one config flag. Benchmark your p95 latency before and after. Run it for a week and compare your CPU usage bill.

The more interesting decision is what to cache and for how long. Start with the obvious: public pages, API responses that change infrequently, static assets rendered by your Worker. Measure your cache hit ratio. A ratio under 50% means you are either caching the wrong things or your content changes too fast for the TTL you set. A ratio above 90% means you are saving serious money and delivering noticeably faster pages.

For SaaS builders: this changes the economics of edge-rendered apps. The CPU billing on Cloudflare Workers was already cheap. With Workers Cache, the marginal cost of serving a page to a thousand users versus one user drops toward zero. That matters for any product where traffic scales unevenly, and the gap between a product going viral and staying quiet is largely about whether your infrastructure costs stay flat.

For framework authors: Workers Cache gives you a caching primitive that your adapter can control programmatically. Expect to see frameworks surface cache configuration in their own config layers, letting developers set per-route cache policies without touching Wrangler.