Vercel's Edge Network caches your content at the edge in order to serve data to your users as fast as possible. Vercel's caching is available for all deployments and domains on your account, regardless of the pricing plan.
Vercel's caching mechanism is centered around the Edge Network, which caches your content globally to serve data to your users as quickly as possible.
Static caching is automatic for all deployments, requiring no manual configuration. However, if you want to cache dynamic content through Edge Functions and Serverless Functions, including SSR, you can do so by adding the Cache-Control
headers to your response. When you specify Cache-Control
headers in a function, responses will be cached in the region the function requested from.
The Cache-Control
field is an HTTP header specifying caching rules for 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 Vercel's Edge Network, the following criteria must be met:
- Request uses
GET
orHEAD
method. - Request does not contain
Range
header. - Request does not contain
Authorization
header. - Response uses
200
,404
,301
, or308
status code. - Response does not exceed
10MB
in content length. - Response does not contain the
set-cookie
header. - Response does not contain the
private
,no-cache
orno-store
directives in theCache-Control
header.
Vercel does not allow bypassing the cache for static files by design.
Static files are automatically cached at the edge after the first request and are cached for up to 31 days on Vercel's Edge Network.
- If a static file is unchanged, the cached value can persist across deployments due to the hash used in the filename
- Optimized images cached will persist between deployments
- The default
Cache-Control
header containspublic
,max-age=0
,must-revalidate
to prevent clients (e.g. browsers) from caching the file locally
In order for Vercel's Edge Network to cache the response of Serverless and Edge Functions, you need to include the response header Cache-Control
with any of the following directives:
Server-side caching headers are used to cache the response at the edge. In order for the Vercel Edge Network to cache the response of Serverless and Edge Functions, you need to include the response header Cache-Control
with any of the following directives:
s-maxage=N
s-maxage=N, stale-while-revalidate=N
proxy-revalidate
and stale-if-error
are not currently supported.For more separate control over caching on Vercel and downstream CDNs, you can use the CDN-Cache-Control
header or the Vercel-specific Vercel-CDN-Cache-Control
header.
If you set Cache-Control
without a CDN-Cache-Control
, the Vercel Edge Network strips s-maxage
and stale-while-revalidate
from the response Cache-Control
header 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.
Edge Function
export default async function handler(req) {
return new Response(
JSON.stringify({
message: 'Hello, world!',
}),
{
status: 200,
headers: {
'content-type': 'application/json',
'cache-control': 'public, s-maxage=1200, stale-while-revalidate=600',
},
},
);
}
export const config = {
runtime: 'edge',
};
See the full example in the examples repository.
Serverless Functions
Set the Cache-Control
header in your Next.js API Routes by using the response.setHeader
method:
export default function handler(request, response) {
response.setHeader('Cache-Control', 's-maxage=86400');
response.status(200).json({ name: 'John Doe' });
}
A Next.js API Route that sends a JSON response and caches that response for one day.
Cache-Control
headers cannot be set using next.config.js
or vercel.json
(for other frameworks) files.Vercel supports the CDN-Cache-Control
header, which allows you to control your CDN cache separately from the browser's cache. You can also use Vercel-CDN-Cache-Control
to control Vercel's CDN cache in specific.
The following example instructs:
- Vercel's Edge Cache to have a TTL (Time To Live) of
3600
seconds - Downstream CDNs to have a TTL of
60
seconds - Clients to have a TTL of
10
seconds
import type { NextApiResponse } from 'next';
export default function handler(response: NextApiResponse) {
response.setHeader('Vercel-CDN-Cache-Control', 'max-age=3600');
response.setHeader('CDN-Cache-Control', 'max-age=60');
response.setHeader('Cache-Control', 'max-age=10');
return response.status(200).json({ name: 'John Doe' });
}
See the CDN-Cache-Control section of our Headers docs to learn more.
max-age=N, public
max-age=N, immutable
Where N
is the number of seconds the response should be cached. The response must also meet the caching criteria mentioned earlier.
See our docs on Cache-Control headers to learn how to best use Cache-Control
directives on Vercel's Edge Network.
Every deployment has a unique key used for caching based on the deployment URL created at build time. This key ensures that users never see content from a previous deployment.
The cache is automatically purged upon a new deployment being created. If you ever need to invalidate Vercel's Edge Network cache, you can always re-deploy.
The x-vercel-cache
header is included in HTTP responses to the client, and describes the state of the cache.
See our headers docs to learn more.
Vercel's Edge Network cache is segmented by region. The following caching limits apply to Vercel Function responses:
- Max Cacheable Response Size = 10MB
- Max Cache Time = 31 days
s-maxage
max-age
stale-while-revalidate
While you can put the maximum time for server-side caching, cache times are best-effort and not guaranteed. If an asset is requested often, it is more likely to live the entire duration. If your asset is rarely requested (e.g. once a day), it may be evicted from the regional cache.
Vercel does not currently support using prox-revalidate
and stale-if-error
for server-side caching.