cdn-caching

name	cdn-caching
description	Debug Vercel CDN caching — cache hit rate, stale content, revalidation behavior, ISR + PPR, per-request cache reasons (cacheReason) and PPR state (ppr_state), and costs.
metadata	{"priority":6,"docs":["https://vercel.com/docs/caching","https://vercel.com/docs/caching/cdn-cache","https://vercel.com/docs/incremental-static-regeneration","https://vercel.com/docs/cli/metrics"],"bashPatterns":["\\bvercel\\s+cache\\s+(purge|invalidate|dangerously-delete)\\b"],"promptSignals":{"phrases":["cache hit rate","isr cost","isr read units","isr write units","stale content","x-vercel-cache","cache reason","cacheReason","x-vercel-cache-reason","ppr state","ppr_state","x-vercel-ppr-state","stale_time","stale_tag","stale_error","draft_mode","prerender_bypass"],"allOf":[["cache","debug"],["stale","cache"],["revalidation","count"],["cache","reason"],["why","stale"],["why","bypass"],["cache","miss"]],"anyOf":["revalidate","prerender","invalidate","draft mode","crawler","cold cache","request collapsed"],"minScore":6}}
retrieval	{"aliases":["cache reason","ppr state","cache hit rate","stale content"],"intents":["why is my page stale","why is this request a bypass","why was this a cache miss"],"entities":["cacheReason","ppr_state","collapsed","draft_mode","prerender_bypass","stale_time","stale_tag","stale_error"]}
chainTo	[{"pattern":"use cache|cacheLife|cacheTag","targetSkill":"next-cache-components","message":"Next.js cache directives detected — loading Cache Components guidance for revalidate/tag tuning."}]

Vercel Caching

You are an expert in understanding Vercel's caching infrastructure, and how the CDN Cache, ISR, and PPR work.

Core Knowledge

• ISR (and PPR, a rendering strategy built on it) is a framework feature — Next.js, SvelteKit, Nuxt, and Astro all use it on Vercel, and the layers, metrics, and CLI here apply regardless. (For caching data between your function and a backend, that's the Runtime Cache — a separate layer; see References.)
• PPR (Partial Prerendering) — a rendering strategy, not a cache layer: the static shell lives in the ISR cache while a function renders the dynamic holes per request and streams them into the same response. A route with holes still invokes the function on a shell hit; a holeless route is just ISR (a pure prerender HIT).

How caching works

Vercel caches at multiple layers between the visitor and your backend. A request reaches the nearest PoP, which routes to a Vercel region; the CDN then checks each layer in order and returns a cached response as soon as one is available, so your function runs only when nothing upstream has a valid copy.

Cache layers

• CDN cache — regional, ephemeral. On a hit the region returns the response with no function call. Reads/writes are free.
• ISR cache — durable, in a single Function region. On a CDN miss, Vercel reads here before invoking your function (cache shielding), then replicates the result back to the CDN. Survives deploys for 31 days or until revalidated; reads/writes are billed in 8 KB units.
• Function invocation — runs only if neither cache has a valid copy. It may read the Runtime/data cache (a separate layer; see References) and your backend, then Vercel stores the response in the ISR cache.
• Image cache — optimized images, cached on the CDN after the first transform.
• Purges propagate globally in ~300 ms.

Request collapsing: when many requests hit the same uncached path at once, Vercel collapses them into one function invocation per region to protect the origin.

Key concepts

• Cache hit rate — share served from cache (HIT/STALE/PRERENDER) versus origin (MISS/REVALIDATED). Measure it over cacheable requests — exclude and (redirects, errors, uncacheable methods), or they drag the ratio down for non-cache reasons. Low hit rate means more origin load and higher latency.