To learn about cache keys, manually purging the cache, and the differences between invalidate and delete methods, see Purging Vercel CDN cache

Runtime cache for caching data within your functions during execution and Remote cache for caching build artifacts.

When to use CDN cache

CDN cache is best when you want to cache complete HTTP responses (entire pages, API responses, or static assets) at the edge, close to your users, such as in the following scenarios:

• Static pages that are the same for all users
• API responses that don't change frequently
• Static assets like images, fonts, and JavaScript bundles
• Server-rendered pages with predictable cache lifetimes

CDN Cache isn't the right fit when:

• You need user-specific content without the Vary header (consider Runtime Cache)
• Responses include sensitive user data
• Content changes on every request to the same url

How to cache responses

You can cache responses on Vercel with Cache-Control headers defined in:

1. Responses from Vercel Functions
2. Route definitions in vercel.json or next.config.js

You can use any combination of the above options, but if you return Cache-Control headers in a Vercel Function, it will override the headers defined for the same route in vercel.json or next.config.js.

Using Vercel Functions

To cache the response of Functions on Vercel's CDN, you must include Cache-Control headers with any of the following directives:

s-maxage=N

s-maxage=N, stale-while-revalidate=Z

s-maxage=N, stale-while-revalidate=Z, stale-if-error=Z

proxy-revalidate is not currently supported.

The following example demonstrates a function that caches its response and revalidates it every 1 second:

If you're building your app with Next.js, you should use next.config.js rather than vercel.json. The following example demonstrates a next.config.js file that adds Cache-Control headers to a route:

Cache control options

You can cache dynamic content through Vercel Functions, including SSR, by adding Cache-Control headers to your response. When you specify Cache-Control headers in a function, responses will be cached in the region the function was requested from.

See our docs on Cache-Control headers to learn how to best use Cache-Control directives on Vercel's CDN.

CDN-Cache-Control

Vercel supports two Targeted Cache-Control headers:

• CDN-Cache-Control, which allows you to control the Vercel CDN Cache or other CDN cache separately from the browser's cache. The browser will not be affected by this header
• Vercel-CDN-Cache-Control, which allows you to specifically control Vercel's Cache. Neither other CDNs nor the browser will be affected by this header

By default, the headers returned to the browser are as follows:

If you set Cache-Control without a CDN-Cache-Control, the Vercel CDN strips s-maxage and stale-while-revalidate from the response before sending it to the browser. To determine if the response was served from the cache, check the x-vercel-cache header in the response.

Vary header

The Vary response header instructs caches to use specific request headers as part of the cache key. This allows you to serve different cached responses to different users based on their request headers.

Vary header only has an effect when used in combination with Cache-Control headers that enable caching (such as s-maxage). Without a caching directive, the Vary header has no behavior.

When Vercel's CDN receives a request, it combines the cache key (described in the Cache Invalidation section) with the values of any request headers specified in the Vary header to create a unique cache entry for each distinct combination.

High-cardinality headers

If a route you expect to be cached returns x-vercel-cache: MISS with this reason, check the Vary header your origin sends. If the response doesn't actually change with that header, remove it from Vary and the response becomes cacheable again.

Use cases

Accept and Accept-Encoding headers as part of the cache key by default. You don't need to explicitly include these headers in your Vary header.

The most common use case for the Vary header is content negotiation, serving different content based on:

• User location (e.g., X-Vercel-IP-Country)
• Language preferences (e.g., Accept-Language)
• Response format for an API that serves more than one (e.g., a custom X-Api-Version)

Pick the narrowest header that captures the difference. Varying on User-Agent to serve two layouts, for example, splits the cache across every browser and version string your visitors send, when a header that holds only the value you branch on would produce two entries.

Example: Country-specific content

You can use the Vary header with Vercel's X-Vercel-IP-Country request header to cache different responses for users from different countries:

Using vercel.json

Using next.config.js

If you're building your app with Next.js, use next.config.js:

• Use Vary headers selectively, as each additional header exponentially increases the number of cache entries. This doesn't directly impact your bill, but can result in more cache misses than desired
• Only include headers that meaningfully impact content generation
• Prefer a header with a small, known set of values. A header that's close to unique per visitor isn't cacheable at all, as described in High-cardinality headers
• Avoid varying on Referer for traffic-source rendering: browsers send only the referring origin cross-site, and same-origin navigation sends full URLs that fragment the cache. A query parameter, or reading the header in your function, captures the source without the fragmentation
• Consider combining multiple variations into a single header value when possible
• Set Vary on the routes that need it rather than globally in middleware or a proxy, so one header doesn't make every route uncacheable

• Request uses GET or HEAD method.
• Request doesn't contain Range header.
• Request doesn't contain Authorization header.
• Response uses 200, 404, 410, 301, 302, 307 or 308 status code.
• Response doesn't exceed 10MB in content length.
• Response doesn't contain the set-cookie header.
• Response doesn't contain the private, no-cache or no-store directives in the Cache-Control header.
• Response doesn't contain a Vary header naming a high-cardinality header, such as Cookie.

Response doesn't contain Vary: * header, which is treated as equivalent to Cache-Control: private.