SYSTEM Cited by 1 source

Cloudflare Workers Cache

Definition

Workers Cache is Cloudflare's regionally-tiered HTTP cache that sits in front of a Worker, configured by a single Wrangler config block and standard Cache-Control response headers. On a cache hit the Worker doesn't run and no CPU time is billed.

Architecture

Workers Cache inverts Cloudflare's original 2017 model (Worker sits in front of the cache) to place the cache in front of the Worker. This is the missing piece for server-side rendering on Workers: render once, cache, serve as static until TTL expires.

Two-tier topology (default, no configuration)

User → [Lower-tier cache (nearest POP)] → [Upper-tier cache (regional)] → Worker

• Lower tier: exists in every data center that receives traffic for the Worker.
• Upper tier: fewer locations, aggregates fills across the network. The first request anywhere populates the upper tier; subsequent requests from any data center serve from it without invoking the Worker.

Worker-owned, not zone-owned

The cache belongs to the Worker, not to a Cloudflare zone:

• Zone Cache Rules, Page Rules, file-extensions list do not apply.
• The cache follows the Worker across custom domains, workers.dev, preview URLs, service bindings, and Workers for Platforms tenants.
• Preview URLs get isolated caches (testing doesn't poison production).
• Purges (ctx.cache.purge(...)) are scoped to the Worker's entrypoint.

Per-entrypoint caching

Workers Cache sits in front of every Worker entrypoint — the default export, every named WorkerEntrypoint, and every ctx.exports call. The Wrangler exports map controls which entrypoints cache:

{
  "cache": { "enabled": true },
  "exports": {
    "default": { "type": "worker", "cache": { "enabled": false } },
    "CachedBackend": { "type": "worker", "cache": { "enabled": true } }
  }
}

This creates composable memoization stages within a single deployable unit — gateway always runs (auth, routing), expensive backend runs only on miss.

Multi-tenant safety via ctx.props

When a gateway Worker calls a cached backend via service binding with ctx.props containing a user/tenant ID, the props become part of the cache key. One user's response can never leak into another user's cache. Combined with stripping Authorization (to avoid Cloudflare's automatic bypass for auth headers), this lets authenticated APIs be cached per-user at the edge.

Content negotiation via Vary

Standard HTTP Vary header support — separate cached variants per distinct request-header combination. No allowlist of allowed Vary headers. Vary: * disables caching entirely.

Key properties

Property	Detail
Configuration	"cache": { "enabled": true } in wrangler.jsonc
Caching semantics	Standard HTTP Cache-Control + Vary + Cache-Tag
Tier count	2 (lower per-POP + upper regional)
Tiered caching config	None required (default)
Purge methods	By tag, path prefix, purgeEverything (scoped to entrypoint)
stale-while-revalidate	Full support — stale served immediately, Worker refreshes in background
Cache hit billing	Standard request rate; zero CPU time
Max cacheable size (launch)	512 MB (temporary; standard per-plan limits planned)
Smart Placement interaction	Composes — tiers checked first, only full miss routes to placed Worker

Composition patterns

• Near-user + near-data: Gateway Worker (near user) → cached backend Worker (near data via Smart Placement). Cache hit → no data-center hop.
• Caching a Durable Object: Wrap DO reads behind a cached entrypoint. Writes go to DO directly and purge by tag.
• Normalizing before caching: Outer entrypoint canonicalizes URL / restores headers, forwards to a cached inner entrypoint that sees only the canonical form.

Framework support

• Astro: Built-in cacheCloudflare provider — auto-sets headers, attaches Cache-Tag, provides cache.invalidate().
• TanStack Start, Vinext (Next.js): Planned.

Seen in

• (Source: sources/2026-07-06-cloudflare-workers-cache)