Cloudflare Workers Cache: Edge Caching for Serverless Origins

Cloudflare Workers Cache: Edge Caching for Serverless Origins

Cloudflare has launched Workers Cache, a tiered caching system that sits directly in front of a Worker. This architecture allows Cloudflare to serve cached responses without invoking the Worker, eliminating CPU billing for cache hits and reducing latency for end users.

Architecture Shift: Worker as the Origin

Historically, Cloudflare Workers sat in front of the cache and the origin. This was ideal for request transformation, URL rewriting, or A/B testing before a request reached the cached origin. However, as modern frameworks like Astro, Next.js, Remix, and SvelteKit increasingly use Workers as the primary server (the origin), the previous model meant every request triggered a Worker invocation, even for identical responses.

Workers Cache flips this model. By placing the cache in front of the Worker, Cloudflare can now serve a response directly from the edge. If a fresh cached response exists, the Worker does not run, and no CPU time is billed. On a miss, the Worker executes once, populates the cache, and subsequent requests are served from the cache globally.

Key Technical Features

Standardized HTTP Control

Workers Cache is configured via a single line in wrangler.jsonc and managed using standard HTTP headers:

  • Cache-Control: Defines the TTL (Time-to-Live) and caching behavior.
  • stale-while-revalidate: Allows Cloudflare to serve a stale response immediately while refreshing the content in the background, ensuring users never wait for a re-render.
  • Vary: Enables content negotiation. Cloudflare stores separate cached variants based on the request headers specified (e.g., Accept-Language or Accept-Encoding), ensuring the correct representation is served to each client.
  • Cache-Tag: Allows for programmatic, granular invalidation of specific content groups via ctx.cache.purge().

Regionally Tiered Caching

Every Worker with caching enabled uses a two-tier topology by default:

  1. Lower Tier: Located in the data center closest to the user.
  2. Upper Tier: A regional aggregator that fills the lower tiers.

This structure ensures that the first request anywhere in the world populates the upper tier, significantly increasing the cache hit ratio across the entire network compared to a flat cache.

Multi-Tenant Safety with ctx.props

To support authenticated or user-specific data, Workers Cache integrates with ctx.props. When a Worker is called via a service binding, any identifiers passed in ctx.props (such as a userId or tenantId) become part of the cache key. This prevents data leakage between users while still allowing authenticated responses to be cached at the edge.

Advanced Composition Patterns

Because Workers Cache sits in front of every Worker entrypoint (including named WorkerEntrypoint and ctx.exports calls), developers can build applications as a chain of memoized stages:

  • Gateway Stage: An outer entrypoint (caching disabled) that handles authentication and request normalization.
  • Backend Stage: An inner entrypoint (caching enabled) that performs expensive data fetching and rendering.

This allows the "gateway" to run on every request to ensure security, while the "backend" only runs on a cache miss. This pattern can be extended to wrap Durable Objects or canonicalize URLs by stripping tracking parameters before the request hits the cached entrypoint.

Billing and Observability

Billing Model

Cache hits reduce costs by eliminating CPU time charges, though they still incur the standard Workers request rate fee.

Outcome Request Charge CPU Time Charge
Cache HIT Standard Rate Not Billed
Cache MISS Standard Rate Billed
Cache BYPASS Standard Rate Billed

Note: Requests that were previously free—such as static asset requests and worker-to-worker invocations—are now billed at the standard request rate when caching is enabled, as they must consult the cache.

Observability

Cache performance is integrated into the Workers Observability dashboard, providing per-invocation data on hits, misses, updates (SWR), and bypasses to help developers tune their max-age and stale-while-revalidate settings.

Community Perspectives

While the technical implementation was praised for its adherence to HTTP standards, some community members expressed concerns regarding billing changes:

"You now get billed for static asset requests! This makes no sense to me... it sounds like a bug that just happens to generate them more money."

Others highlighted the significance of the feature for server-side rendering (SSR) performance:

"A big worry was always 'why does workers sit in front of my cache? that's a waste of an invocation if i'm returning a cached result'"

Framework Integration

Workers Cache is already integrated into the Astro Cloudflare adapter via the cacheCloudflare provider, allowing developers to define routeRules for maxAge and swr directly in the Astro configuration.

Sources