Skip to main content
sitewarm
Rank 3 of 10 on caching criteria

Vercel CDN caching guide

Vercel · reviewed against the vendor documentation listed below

How the Vercel CDN caches: x-vercel-cache values, Vercel-CDN-Cache-Control, cache tags with invalidate or delete, and why a deploy starts its own cache.

Part of the Top 10 CDNs in 2026 comparison. New to the topic? Start with why cache warming matters.

Caching at a glance

Cache status on the response
x-vercel-cache: HIT, MISS, STALE, PRERENDER, REVALIDATED or BYPASS.
TTL controls
Vercel-CDN-Cache-Control takes precedence over CDN-Cache-Control, which takes precedence over Cache-Control. s-maxage, stale-while-revalidate and stale-if-error are removed before the response reaches the browser.
Purge
Cache tags (Vercel-Cache-Tag header, addCacheTag or Next.js cacheTag). Invalidate marks tagged content stale and revalidates it in the background; delete makes the next request go to the origin. Purging a tag clears the CDN, Runtime and Data caches. CLI: vercel cache invalidate --tag, vercel cache dangerously-delete --tag, vercel cache purge.
Tiering and origin protection
Function responses are cached in the region the function was requested from. No shared tier is documented in the pages we reviewed.
Edge compute
Vercel Functions and Routing Middleware.

Strengths for caching

  • A detailed x-vercel-cache value on every response, including STALE and REVALIDATED.
  • Invalidate by tag keeps stale content available, and the docs warn that delete can cause a cache stampede.
  • stale-while-revalidate and stale-if-error are both supported for the CDN cache.

Watch-outs

  • A new deployment does not purge the cache, but each deployment has its own cache key, so a newly promoted deployment starts with its own, empty cache. Static files whose hashed names did not change, and optimized images, can persist across deployments.
  • Cache keys are not configurable.
  • Cache times are best-effort and not guaranteed; rarely requested content can be evicted from the regional cache.

Cache warming on Vercel

On Vercel, the deploy itself is the cold start. Promoting a new deployment does not purge anything, but the new deployment's pages have a different cache key, so the first visitor to each page in each region gets a MISS and runs the function. That is the window cache warming closes.

Because the cache is segmented by region, a warming request fills the region it reached. Warm from the regions your visitors use, and read x-vercel-cache to confirm: PRERENDER and HIT mean the page came from cache.

curl -sI https://example.com/ | grep -iE '^(x-vercel-cache|x-vercel-id)'
# x-vercel-cache: MISS   (first request after promoting a deployment)
# x-vercel-cache: HIT

For content changes without a deploy, tag responses and invalidate the tag rather than deleting it: invalidated entries are served stale while they revalidate, so the origin sees one request per region instead of a burst. The Top 10 CDNs comparison explains how this was scored.

Frequently asked questions

Does a Vercel deployment clear the CDN cache?

No. Each deployment has its own cache key, so a new deployment starts with its own cache and the previous deployment's cache is left as it was. Unchanged hashed static files and optimized images can persist across deployments.

Should I invalidate or delete a Vercel cache tag?

Invalidate in most cases: tagged entries are marked stale and revalidated in the background. Delete forces the next request to the origin, and Vercel warns it can cause a cache stampede.

Related terms

Vercel documentation

  1. Vercel: CDN Cachehttps://vercel.com/docs/caching/cdn-cache
  2. Vercel: Purging the CDN cachehttps://vercel.com/docs/caching/cdn-cache/purge
  3. Vercel: Cache-Control headershttps://vercel.com/docs/caching/cache-control-headers
  4. Vercel: Response headershttps://vercel.com/docs/headers/response-headers
  5. Vercel: vercel cache (CLI)https://vercel.com/docs/cli/cache

Warm your cache after every deploy

sitewarm requests the pages in your sitemap after a deploy and reports the cache state the CDN returns for each one, with the vantage point it was measured from.

Start warmingWhy cache warming