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
orHEAD
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
, or308
status code. - Response must not exceed
10MB
in content length. - Response must not contain the
no-cache
directive in theCache-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:
Value | Description |
---|---|
MISS | The response was not found in the edge and thus fetched from an origin server. (Learn more) |
HIT | The response was served from the edge. (Learn more) |
STALE | The response is stale (served from the edge). A background request to the origin was made to get a fresh version. (Learn more) |
BYPASS | The cache was bypassed and so the response was served from an origin server. (Learn more) |
PRERENDER | The response was served from static storage. (Learn more) |
REVALIDATED | The response was served from origin and the cache was refreshed due to an authorization from the user in the incoming request. (Learn more) |
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.