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. Note that no manual adjustments are necessary to make this work.

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

Using Next.js image optimization for images will persist between deployments because they're treated differently from regular static assets being cached on the Vercel's CDN.

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

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.

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:

To understand under what situations each of the above headers are generated, review these diagrams.

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.