From vercel
Debug Vercel CDN caching including cache hit rate, stale content, revalidation behavior, ISR, PPR, and cost metrics.
How this skill is triggered — by the user, by Claude, or both
Slash command
/vercel:cdn-cachingThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are an expert in understanding Vercel's caching infrastructure, and how the CDN Cache, ISR, and PPR work.
You are an expert in understanding Vercel's caching infrastructure, and how the CDN Cache, ISR, and PPR work.
prerender HIT).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.
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.
Cache hit rate — share served from cache (HIT/STALE/PRERENDER) versus origin (MISS/REVALIDATED). Measure it over cacheable requests — exclude BYPASS and (not set) (redirects, errors, uncacheable methods), or they drag the ratio down for non-cache reasons. Low hit rate means more origin load and higher latency.
Revalidation — refreshing cached content. Time-based runs automatically after an interval; on-demand runs when you call an API. Both use stale-while-revalidate: visitors keep getting the cached version while the new one regenerates in the background.
Invalidate vs. dangerously-delete — two ways to clear content, with very different blast on hit rate:
invalidateByTag, Next.js revalidateTag/revalidatePath) = stale-while-revalidate. Keeps serving stale while refreshing in the background → response shows x-vercel-cache: STALE.dangerouslyDeleteByTag, Next.js updateTag or a revalidate with no lifetime) = hard removal. The next request blocks in the foreground to regenerate → x-vercel-cache: REVALIDATED.Cache tags & blast radius — tags group cached entries so one call can clear many. A coarse tag attached to thousands of paths has a large blast radius: a single write drops them all and the hit rate collapses until they re-warm. Prefer granular tags (product-${id}) plus a roll-up tag.
Cache status / cache reason (x-vercel-cache response header):
| Value | Meaning |
|---|---|
HIT | Served from cache; no function ran |
MISS | Not cached; origin/function ran |
STALE | Served stale while revalidating in background (SWR / invalidate) |
PRERENDER | Served a prerendered ISR/PPR shell |
REVALIDATED | Foreground revalidation after a delete (or Pragma: no-cache) |
BYPASS | Caching skipped (no-store, private, cookies, etc.) |
Reach for the Vercel CLI. vercel metrics gives aggregate numbers (requires Observability Plus); vercel logs shows per-request behavior.
Metrics need to be queried by team and project (-S <team> -p <project>). Filter production with -f "environment eq 'production'" (there is no --prod flag). Run vercel metrics schema <metric> to discover dimensions; use -F json for machine-readable output. With -g, remember --limit is per time bucket — omit -g when you need totals across the whole window.
Start here for an overall picture of how well caching is working.
Step 1 — overall split. Group vercel.request.count by cache_result. Treat HIT, STALE, and PRERENDER as cache-served; focus investigation on MISS. Exclude BYPASS and (not set) when computing a hit rate over cacheable traffic (see Debugging BYPASS traffic). STALE means stale-while-revalidate is working — dig into revalidation frequency in Analyzing ISR costs, not here.
vercel metrics vercel.request.count -S <team> -p <project> \
-f "environment eq 'production'" --group-by cache_result --since 24h
Step 2 — where misses concentrate. Split the MISS bucket (and optionally STALE) by path_type, then by route or request_path:
vercel metrics vercel.request.count -S <team> -p <project> \
-f "environment eq 'production' and cache_result eq 'MISS'" \
--group-by path_type --since 24h
vercel metrics vercel.request.count -S <team> -p <project> \
-f "environment eq 'production' and cache_result eq 'MISS' and path_type eq 'prerender'" \
--group-by request_path --since 24h
What to expect: prerender routes (static shells, ISR pages) should show a high share of HIT/PRERENDER. A prerender path with a disproportionate MISS count is your short list for per-path header inspection (curl above) and code review.
streaming_func routes render dynamically by default, but you can still cache them with Cache-Control headers — matching requests are cached on the CDN. Each cache entry varies by Vary headers (cookies, RSC, etc.) as well as path and query parameters, so expect more cache keys and a lower hit rate than a fully static prerender route.
Once you know hit rate, quantify ISR spend and whether revalidation — not traffic volume — is driving it.
Utilization vs. ISR billing. Utilization is vercel.request.count — total request volume. ISR cost is billed separately in 8 KB units: read_units when the regional CDN misses and falls through to the ISR cache, and write_units on every revalidation/regeneration. The regional CDN shields ISR heavily — most requests never touch the ISR layer, so read_units will be far below request count. Do not compare read_units to write_units as a utilization check; focus on write_units (revalidation cost) and how they relate to total traffic.
vercel metrics vercel.request.count -S <team> -p <project> -a sum --since 24h
vercel metrics vercel.isr_operation.write_units -S <team> -p <project> -a sum --since 24h
Which routes revalidate most. Break write units down by route and request_path to find paths that regenerate often relative to traffic:
vercel metrics vercel.isr_operation.write_units -S <team> -p <project> \
-a sum --group-by route --since 24h
vercel metrics vercel.isr_operation.write_units -S <team> -p <project> \
-a sum --group-by request_path --since 24h
Regeneration vs. serving. Group write units by path_type — concentration in background_func confirms revalidation (not per-request dynamic work) is the cost driver.
Time-based vs. tag-based revalidation. Time-based intervals regenerate on a schedule whether or not content changed — often inefficient. Tag-based on-demand revalidation is usually better, but an overly broad tag has a large blast radius: one invalidate drops every entry that carries it.
cache_tags. If many unrelated routes show near-identical write counts, a shared hot tag is invalidating them in lockstep (e.g. every blog post rewriting at the same rate because they share one broad blogPost tag):vercel metrics vercel.isr_operation.write_units -S <team> -p <project> \
-a sum --group-by cache_tags --since 24h
vercel.request.count by triggering_tag to see which tags fire most often (triggering_tag is on request count only, not ISR operation metrics. It is one of the tags that triggered the page to be stale):vercel metrics vercel.request.count -S <team> -p <project> \
-f "triggering_tag ne null" --group-by triggering_tag --since 24h
Tags with a large blast radius that revalidate frequently are the usual root cause of high write_units. Prefer granular tags (product-${id}) and on-demand invalidation over short time-based intervals for event-driven content.
Confirm in code. Metrics tell you which tag is hot; the repo tells you why. Grep for the tag's invalidation call site — revalidateTag(, invalidateByTag(, updateTag(, dangerouslyDeleteByTag( — and read the trigger. A CMS webhook or a sync cron that invalidates a broad tag on every event (instead of a specific ${type}:${id}) is the classic amplifier.
The largest legitimate sources of BYPASS are Draft Mode and SEO crawlers. Draft Mode must bypass cache so editors see live content. SEO bots must receive the full response — especially on PPR routes where the static shell and dynamic holes are assembled at request time — so crawlers index what users actually see. That BYPASS is expected, not a misconfiguration.
Before tuning headers or revalidate intervals, confirm what's left after those two buckets:
vercel metrics vercel.request.count -S <team> -p <project> \
-f "cache_result eq 'BYPASS'" --group-by bot_category --since 24h
vercel metrics vercel.request.count -S <team> -p <project> \
-f "cache_result eq 'BYPASS'" --group-by user_agent --since 24h
vercel metrics vercel.request.count -S <team> -p <project> \
-f "cache_result eq 'BYPASS'" --group-by request_method --since 24h
The Firewall/WAF with the vercel-firewall skill can be used to manage verified SEO crawlers, block abusive bots, and rate-limit junk traffic before it distorts your hit-rate picture.
revalidate intervals with on-demand revalidateTag / invalidateByTag when content changes — time-based regeneration runs whether or not anything changed. If using Cache Components, analyze cacheLife calls with the next-cache-components skill.blogPost:<id>, not a generic blogPost/page tag — one broad invalidate regenerates everything that carries it.revalidate / cacheLife, SvelteKit isr, Nuxt routeRules, Astro). For Next.js Cache Components, see the next-cache-components skill.CDN-Cache-Control headers to cache dynamic functions.curl -sSI https://<host>/<path> | grep -iE 'x-vercel-cache|x-matched-path|cache-control|vary|age|set-cookie'
This zero-dependency first reach shows the status (x-vercel-cache), the cache directives (Cache-Control / CDN-Cache-Control / Vercel-CDN-Cache-Control), and — crucially — x-matched-path, which reveals rewrites like /precomputed/exp~.../... that expose experiment/flag precomputation. vary flags personalization (RSC, cookies); set-cookie forces BYPASS. For a per-phase timing breakdown, vercel httpstat /some/path (CLI v48.9.0+; needs the httpstat tool installed) adds latency stats. A path that should cache but shows MISS/BYPASS usually has private, no-store, max-age=0, a per-request input (cookies/headers/searchParams), or an uncacheable method (see FAQ).
Inspect one request. When metrics or headers give you a request ID, pull the full log record:
vercel logs --request-id <request-id> --json
Use --json so the agent can parse cache status, path, and timing fields programmatically.
/precomputed/exp~.../... paths), and flags × routes × PPR segments multiply into thousands of ISR entries (also a middleware-invocation cost). Fix: collapse the variant matrix (retire finished experiments), or accept the cost.prerender HIT — see Key concepts.)vercel-firewall — manage verified SEO crawlers, block abusive bots, and rate-limit junk BYPASS traffic.runtime-cache — caching data between your function and a backend (per-region key-value / data cache). A different layer from the CDN/ISR caches; use it to cache an API response or query result inside a function.next-cache-components — Next.js use cache, cacheLife, cacheTag, and revalidate tuning (one framework's ISR/PPR controls).npx claudepluginhub vercel/vercel-plugin --plugin vercel-pluginOptimizes Vercel deployments with edge caching, bundle analysis, cold start reduction, and Core Web Vitals improvements for faster page loads and lower latency.
Controls caching on Netlify's CDN using cache headers, stale-while-revalidate, on-demand purge, cache tags, and durable cache. Covers Cache-Control, Netlify-CDN-Cache-Control, and framework-specific patterns.
Audits deployed Vercel apps for cost and performance issues using production metrics, config, and version-aware recommendations.