Caching

The Vercel Edge Network caches your content at the edge in order to serve data to your users as fast as possible.

Static caching is automatic for all deployments. This means that no changes need to be made to headers. You get the best performance possible out of the box with zero configuration required.

Cacheable Responses

The Cache-Control field is an HTTP header that specifies a set of caching rules for both client (browser) requests and server responses. A cache must obey the requirements defined in the Cache-Control header. For server responses to be successfully cached with the Vercel Edge Network, the following criteria must be met:

• Request must use GET or HEAD method.
• Request must not contain the Range header.
• Request must not contain the Authorization header.
• Request must not contain a _vercel_no_cache=1 cookie.
• Request must not contain a ?_vercel_no_cache=1 request parameter.
• Response must use 200, 404, 301, or 308 status code.
• Response must not exceed 10MB in content length.
• Response must not contain the no-cache directive in the Cache-Control header.

Note that Vercel won't allow bypassing the cache for static files. This is by design.

Static Files Caching

Static files are automatically cached at the edge after the first request. There are no manual adjustments necessary to make this work.

Static files are cached for up to 31 days. However, when you redeploy the cache is effectively invalidated so we always serve the latest version. If a file is unchanged it can persist across deployments, as static files are cached by their hash.

By default we return a Cache-Control header containing public, max-age=0, must-revalidate to prevent clients (e.g. browsers) from caching the file locally. This gives you the most flexibility as users get the latest file from our Global CDN immediately after deploying. This can be overridden with the Headers property in your vercel.json file.

Serverless Functions (Lambdas)

In order for our CDN to cache the response of a Serverless Function, you need to include the response header Cache-Control with any of the following directives:

• s-maxage=N
• max-age=N, public
• max-age=N, immutable
• stale-while-revalidate=N
• stale-if-error=N

Where N is the number of seconds the response should be cached. The response must also be cached as detailed above.

Note: proxy-revalidate is not currently supported.

Stale-While-Revalidate

Our CDN supports a powerful recent extension to the Cache-Control header called stale-while-revalidate.

The benefit of using stale-while-revalidate is that we can serve a resource from our CDN cache while simultaneously updating the cache in the background with the response from your Serverless Function.

Some situations where stale-while-revalidate is of great value:

• Your content changes frequently but it takes a significant amount of time to regenerate. For example, an expensive database query or upstream API request.
• Your content changes infrequently but you want to have the flexibility to update it (to fix a typo, for example) and don't wait for the cache to expire.

Here's an example header:

Cache-Control: s-maxage=1, stale-while-revalidate=59

An example Cache-Control header that enables content to be updated in the background.

This tells our CDN the value is fresh for one second. If a request is repeated within the next second, the previously cached value is still fresh. The header x-vercel-cache present in the response will show the value HIT. If the request is repeated between 1 and 60 seconds later, the cached value will be stale but still render. In the background, a revalidation request will be made to populate the cache with a fresh value. x-vercel-cache will have the value STALE until the cache is refreshed.

When the CDN receives a request with Pragma: no-cache (such as when the browser devtools are open), it will bypass the client cache, but will not bypass the CDN cache.

Cache Invalidation

Every deployment has a unique key used for caching based on the deployment url created at build time. This means that users will never see content from a previous deployment and there's normally no need to invalidate it.

The cache is automatically purged upon a new deployment being created. If you ever need to invalidate the CDN cache, you can always re-deploy.

X-Vercel-Cache

Responses include a header called X-Vercel-Cache that contain details about the state of the cache for the resource. Possible values are:

Limits

The cache is global per-region. These limits apply to both static and Serverless Function responses:

• Max Cacheable Response Size = 10MB
• Max Cache Time = 31 days
  • s-maxage
  • max-age
  • stale-while-revalidate

Note: The s-maxage header is best-effort, not guaranteed.