Cache on KV and DO

On Workers every isolate has its own page cache. This page explains what that means for cache.invalidate and when to add a shared tier.

Two tiers

There are two cache tiers. Tier 1 is the per-isolate memory cache inside the wasm: pages (l1_capacity) and job results (job_cache_capacity). Tier 2 is an optional shared store you add with a cache adapter (Cache adapters).

{ path: '/pokemon/{name}', Component: DetailPage, loader: detailLoader,
  cache: { ttl_seconds: 60, tags: ['pokemon', 'team'] } },

Isolates and invalidation

An isolate is one running copy of your Worker. Cloudflare starts and recycles many of them, in many locations, at will. Each has its own tier 1. So:

• A page rendered in one isolate is not a hit in another. The hit rate is lower than on native.
• cache.invalidate is isolate-local without an adapter. The isolate that ran the action drops its entries at once. Every other isolate keeps serving the old page until its route ttl_seconds runs out. Keep ttl_seconds short on Workers if you do not configure an adapter.

Reaching every isolate

To make a mutation visible everywhere within about epoch_interval_ms (default 1 s), configure a cache adapter with a broadcast. The Durable Object adapter does this. The recommended pair keeps page bodies in KV and carries invalidations through a Durable Object:

[cache]
adapter = "cloudflare-kv"
broadcast = "cloudflare-do"
epoch_interval_ms = 5000

[cache.cloudflare]
kv_min_ttl_s = 300

Bindings, options, what each configuration guarantees and the Free-plan cost of polling are on Cache adapters: Cloudflare. The shared contract is on the overview.

Rules that stay the same

• Within one isolate the stamp rules are the native ones: a page whose render started before an invalidation is not stored.
• Date.now() on Workers advances only across I/O, so TTLs are coarse inside a single request. That is harmless.
• A page with Set-Cookie is not cached, as on native.