Update to Vercel

{
  "name": "cdn-caching",
  "description": "Debug Vercel CDN caching — cache hit rate, stale content, revalidation behavior, ISR + PPR, per-request cache reasons (cacheReason), and costs.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 119
    }
  ],
  "skill_md_contents": "---\nname: cdn-caching\ndescription: Debug Vercel CDN caching — cache hit rate, stale content, revalidation behavior, ISR + PPR, per-request cache reasons (cacheReason), and costs.\nmetadata:\n  priority: 6\n  docs:\n    - 'https://vercel.com/docs/caching'\n    - 'https://vercel.com/docs/caching/cdn-cache'\n    - 'https://vercel.com/docs/incremental-static-regeneration'\n    - 'https://vercel.com/docs/cli/metrics'\n  bashPatterns:\n    - '\\bvercel\\s+cache\\s+(purge|invalidate|dangerously-delete)\\b'\n  promptSignals:\n    phrases:\n      - 'cache hit rate'\n      - 'isr cost'\n      - 'isr read units'\n      - 'isr write units'\n      - 'stale content'\n      - 'x-vercel-cache'\n      - 'cache reason'\n      - 'cacheReason'\n      - 'x-vercel-cache-reason'\n      - 'stale_time'\n      - 'stale_tag'\n      - 'stale_error'\n      - 'draft_mode'\n      - 'prerender_bypass'\n    allOf:\n      - [cache, debug]\n      - [stale, cache]\n      - [revalidation, count]\n      - [cache, reason]\n      - [why, stale]\n      - [why, bypass]\n      - [cache, miss]\n    anyOf:\n      - 'revalidate'\n      - 'prerender'\n      - 'invalidate'\n      - 'draft mode'\n      - 'crawler'\n      - 'cold cache'\n      - 'request collapsed'\n    minScore: 6\n---\n\n# Vercel Caching\n\nYou are an expert in understanding Vercel's caching infrastructure, and how the CDN Cache, ISR, and PPR work.\n\n## Core Knowledge\n\n- 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.)\n- **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).\n\n### How caching works\n\nVercel 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.\n\n#### Cache layers\n\n- **CDN cache** — regional, ephemeral. On a hit the region returns the response with no function call. Reads/writes are **free**.\n- **ISR cache** — durable, in a single [Function region](https://vercel.com/docs/functions/configuring-functions/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**.\n- **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.\n- **Image cache** — optimized images, cached on the CDN after the first transform.\n- Purges propagate globally in ~300 ms.\n\n**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.\n\n#### Key concepts\n\n- **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.\n- **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.\n- **Invalidate vs. dangerously-delete** — two ways to clear content, with very different blast on hit rate:\n  - _Invalidate_ (`invalidateByTag`, Next.js `revalidateTag`/`revalidatePath`) = stale-while-revalidate. Keeps serving stale while refreshing in the background → response shows `x-vercel-cache: STALE`.\n  - _Dangerously-delete_ (`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`.\n- **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.\n- **Cache status** (`x-vercel-cache` response header) — the _outcome_:\n\n  | Value         | Meaning                                                          |\n  | ------------- | ---------------------------------------------------------------- |\n  | `HIT`         | Served from cache; no function ran                               |\n  | `MISS`        | Not cached; origin/function ran                                  |\n  | `STALE`       | Served stale while revalidating in background (SWR / invalidate) |\n  | `PRERENDER`   | Served a prerendered ISR/PPR shell                               |\n  | `REVALIDATED` | Foreground revalidation after a delete (or `Pragma: no-cache`)   |\n  | `BYPASS`      | Caching skipped (`no-store`, `private`, cookies, etc.)           |\n\n- **Cache reason** (`cacheReason`) — the finer _explanation_ of that outcome for a single request. The `cache_result` metric lumps all `MISS`es (and all `STALE`s) together; the reason is the only thing that tells them apart. Nine values, three per group:\n\n  | `cacheReason`      | Refines  | Meaning                                                                       |\n  | ------------------ | -------- | ----------------------------------------------------------------------------- |\n  | `cold`             | MISS     | Cache empty for this key/variant (first request or evicted); the function ran |\n  | `collapsed`        | MISS     | Concurrent requests to one uncached path collapsed into a single invocation   |\n  | `error`            | MISS     | An error prevented serving from cache                                         |\n  | `draft_mode`       | → BYPASS | Next.js Draft Mode active — bypassed so editors see live content              |\n  | `prerender_bypass` | → BYPASS | Prerender-bypass cookie/token present                                         |\n  | `crawler`          | → BYPASS | SEO-crawler UA — full response served so bots index real content              |\n  | `stale_time`       | STALE    | Time-based `revalidate` interval elapsed; regenerating in background (SWR)     |\n  | `stale_tag`        | STALE    | Tag invalidated (`revalidateTag` / `invalidateByTag`); regenerating           |\n  | `stale_error`      | STALE    | A revalidation attempt **failed**; serving the last-good copy (a bug signal)  |\n\n  A raw `MISS` with reason `draft_mode` / `prerender_bypass` / `crawler` is **displayed as `BYPASS`** (all usually expected). The three `stale_*` reasons separate a healthy time refresh (`stale_time`) from a broad-tag blast (`stale_tag`) from a failing regen (`stale_error`). Read `cacheReason` from `vercel logs` or the dashboard Logs \"Reason\" row — the `x-vercel-cache-reason` header is internal-only and not visible via `curl`.\n\n## Investigating cache issues\n\nReach for the Vercel CLI. `vercel metrics` gives aggregate numbers (requires [Observability Plus](https://vercel.com/docs/observability/observability-plus)); `vercel logs` shows per-request behavior.\n\nMetrics 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.\n\n### Cache hit rate\n\nStart here for an overall picture of how well caching is working.\n\n**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](#debugging-bypass-traffic)). `STALE` means stale-while-revalidate is working — dig into revalidation frequency in [Analyzing ISR costs](#analyzing-isr-costs), not here.\n\n```bash\nvercel metrics vercel.request.count -S <team> -p <project> \\\n  -f \"environment eq 'production'\" --group-by cache_result --since 24h\n```\n\n**Step 2 — where misses concentrate.** Split the `MISS` bucket (and optionally `STALE`) by `path_type`, then by `route` or `request_path`:\n\n```bash\nvercel metrics vercel.request.count -S <team> -p <project> \\\n  -f \"environment eq 'production' and cache_result eq 'MISS'\" \\\n  --group-by path_type --since 24h\n\nvercel metrics vercel.request.count -S <team> -p <project> \\\n  -f \"environment eq 'production' and cache_result eq 'MISS' and path_type eq 'prerender'\" \\\n  --group-by request_path --since 24h\n```\n\n**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.\n\n`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.\n\n### Analyzing ISR costs\n\nOnce you know hit rate, quantify ISR spend and whether revalidation — not traffic volume — is driving it.\n\n**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.\n\n```bash\nvercel metrics vercel.request.count -S <team> -p <project> -a sum --since 24h\nvercel metrics vercel.isr_operation.write_units -S <team> -p <project> -a sum --since 24h\n```\n\n**Write utilization = cache serves ÷ ISR writes** — cached reads per regeneration.\n\n```bash\n# numerator: cache serves — sum the HIT + STALE + PRERENDER buckets\nvercel metrics vercel.request.count -S <team> -p <project> \\\n  -f \"environment eq 'production' and (cache_result eq 'HIT' or cache_result eq 'STALE')\" \\\n  --group-by route -a sum --since 24h\n# denominator: ISR writes\nvercel metrics vercel.isr_operation.write_units -S <team> -p <project> \\\n  -f \"environment eq 'production'\" --group-by route -a sum --since 24h\n```\n\nHigh is good; near or below ~1 means you regenerate about as fast as the page is read (wasted writes) → lengthen the revalidate interval or move time-based to on-demand tag revalidation.\n\n**Which routes revalidate most.** Break write units down by `route` and `request_path` to find paths that regenerate often relative to traffic:\n\n```bash\nvercel metrics vercel.isr_operation.write_units -S <team> -p <project> \\\n  -a sum --group-by route --since 24h\n\nvercel metrics vercel.isr_operation.write_units -S <team> -p <project> \\\n  -a sum --group-by request_path --since 24h\n```\n\n**Regeneration vs. serving.** Group write units by `path_type` — concentration in `background_func` confirms revalidation (not per-request dynamic work) is the cost driver.\n\n**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.\n\n- **Tag blast radius** — group write units by `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):\n\n```bash\nvercel metrics vercel.isr_operation.write_units -S <team> -p <project> \\\n  -a sum --group-by cache_tags --since 24h\n```\n\n- **What triggered revalidation** — group `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):\n\n```bash\nvercel metrics vercel.request.count -S <team> -p <project> \\\n  -f \"triggering_tag ne null\" --group-by triggering_tag --since 24h\n```\n\nTags 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.\n\n**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.\n\n### Debugging BYPASS traffic\n\nThe 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.\n\nBefore tuning headers or revalidate intervals, confirm what's left after those two buckets:\n\n```bash\nvercel metrics vercel.request.count -S <team> -p <project> \\\n  -f \"cache_result eq 'BYPASS'\" --group-by bot_category --since 24h\n\nvercel metrics vercel.request.count -S <team> -p <project> \\\n  -f \"cache_result eq 'BYPASS'\" --group-by user_agent --since 24h\n\nvercel metrics vercel.request.count -S <team> -p <project> \\\n  -f \"cache_result eq 'BYPASS'\" --group-by request_method --since 24h\n```\n\nThe **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.\n\n## Reducing ISR cost\n\n- **Prefer tag-based over time-based revalidation.** Replace short `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.\n- **Scope tags to specific IDs.** Invalidate `blogPost:<id>`, not a generic `blogPost`/`page` tag — one broad invalidate regenerates everything that carries it.\n- Tune the revalidate interval where your framework declares it (Next.js `revalidate` / `cacheLife`, SvelteKit `isr`, Nuxt `routeRules`, Astro). For Next.js Cache Components, see the `next-cache-components` skill.\n- Use `CDN-Cache-Control` headers to cache dynamic functions.\n\n### Inspect one path\n\n```bash\ncurl -sSI https://<host>/<path> | grep -iE 'x-vercel-cache|x-matched-path|cache-control|vary|age|set-cookie'\n```\n\nThis 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).\n\n**Inspect one request.** When metrics or headers give you a request ID, pull the full log record:\n\n```bash\nvercel logs --request-id <request-id> --json\n```\n\nUse `--json` so the agent can parse cache status, path, and timing fields programmatically.\n\n## FAQ\n\n- **What are prerender variant misses?** When a route uses a dynamic param, each distinct cache-key variant is prerendered and cached separately, so each variant misses on its first hit per region and low-traffic ones rarely stay warm. The most common modern cause is **feature-flag / experiment precomputation** — middleware picks a variant per request (`/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.\n- **Does PPR avoid function invocations?** No — a PPR route has dynamic holes by definition, so the cached shell hit still runs the function to fill them. (A route with _no_ holes is just ISR and serves a pure `prerender` HIT — see Key concepts.)\n- **Why are there more function invocations than PPR requests?** PPR requests have a static shell and a dynamic function invocation. When the static shell needs to be regenerated, it incurs a function invocation on top of the dynamic function for the content.\n\n## Related skills\n\n- `vercel-firewall` — manage verified SEO crawlers, block abusive bots, and rate-limit junk BYPASS traffic.\n- `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.\n- `next-cache-components` — Next.js `use cache`, `cacheLife`, `cacheTag`, and `revalidate` tuning (one framework's ISR/PPR controls).\n\n## References:\n\n- Caching overview: https://vercel.com/docs/caching\n- ISR: https://vercel.com/docs/incremental-static-regeneration\n- Partial Prerendering (PPR): https://vercel.com/docs/partial-prerendering\n- Cache-Control headers: https://vercel.com/docs/caching/cache-control-headers\n- Diagnosing and fixing cache issues (full runbook): https://vercel.com/docs/caching/cdn-cache/debug-cache-issues\n- vercel metrics CLI: https://vercel.com/docs/cli/metrics\n- vercel logs CLI: https://vercel.com/docs/cli/logs\n"
}