Cache-Control headers

You can control how Vercel's CDN caches your Function responses by setting a Cache-Control headers header.

The default value is which instructs both the CDN and the browser not to cache.

We recommend that you set your cache to, adjusting 86400 to the number of seconds you want the response cached. This configuration tells browsers not to cache, allowing Vercel's CDN to cache responses and invalidate them when deployments update.

This directive sets the number of seconds a response is considered "fresh" by the CDN. After this period ends, Vercel's CDN will serve the "stale" response from the edge until the response is asynchronously revalidated with a "fresh" response to your Vercel Function.

is consumed by Vercel's proxy and not included as part the final HTTP response to the client.

The following example instructs the CDN to cache the response for 60 seconds. A response can be cached a minimum of second and maximum of seconds (1 year).

This directive allows you to serve content from the Vercel cache while simultaneously updating the cache in the background with the response from your function. It is useful when:

• Your content changes frequently, but regeneration is slow, such as content that relies on an expensive database query or upstream API request
• Your content changes infrequently but you want to have the flexibility to update it without waiting for the cache to expire

is consumed by Vercel's proxy and not included as part the final HTTP response to the client. This allows you to deliver the latest content to your visitors right after creating a new deployment (as opposed to waiting for browser cache to expire). It also prevents content-flash.

The following example instructs the CDN to:

• Serve content from the cache for 1 second
• Return a stale request (if requested after 1 second)
• Update the cache in the background asynchronously (if requested after 1 second)

The first request is served synchronously. Subsequent requests are served from the cache and revalidated asynchronously if the cache is "stale".

If you need to do a synchronous revalidation you can set the header along with the header. This can be used to understand how long the background revalidation took. It sets the header to .

This directive is currently not supported. is consumed by Vercel's proxy, and will not be included in the HTTP response sent to the client.

This directive is currently not supported.

Using the directive specifies that the response can only be cached by the client and not by Vercel's CDN. Use this directive when you want to cache content on the user's browser, but prevent caching on Vercel's CDN.

When Vercel's CDN receives a request with (such as when the browser devtools are open), it will revalidate any stale resource synchronously, instead of in the background.

Sometimes the directives you set in a header can be interpreted differently by the different CDNs and proxies your content passes through between the origin server and a visitor's browser. To explicitly control caching you can use targeted cache control headers.

The and headers are response headers that can be used to specify caching behavior on the CDN.

You can use the same directives as , but is only used by the CDN.

Origins can set the following headers:

When multiple of the above headers are set, Vercel's CDN will use the following priority to determine the caching behavior:

is exclusive to Vercel and has top priority, whether it's defined in a Vercel Function response or a file. It controls caching behavior only within Vercel's Cache. It is removed from the response and not sent to the client or any CDNs.

is second in priority after , and always overrides headers, whether defined in a Vercel Function response or a file.

By default, configures Vercel's Cache and is used by other CDNs, allowing you to configure intermediary caches. If is also set, only influences other CDN caches.

is a web standard header and last in priority. If neither nor are set, this header will be used by Vercel's Cache before being forwarded to the client.

You can still set while using the other two, and it will be forwarded to the client as is.

The following tables demonstrate how Vercel's Cache behaves in different scenarios:

headers returned from Vercel Functions take priority over headers from or files.

has priority over , even if defined in or .

has priority over both and . It only applies to Vercel, so it is not returned with the other headers, which will control cache behavior on the browser and other CDNs.

• If you want to control caching similarly on Vercel, CDNs, and the client, use
• If you want to control caching on Vercel and also on other CDNs, use
• If you want to control caching only on Vercel, use
• If you want to specify different caching behaviors for Vercel, other CDNs, and the client, you can set all three headers

The following example demonstrates headers that instruct:

• Vercel's Cache to have a TTL of seconds
• Downstream CDNs to have a TTL of seconds
• Clients to have a TTL of seconds

Using configuration, you can assign custom headers to each response.

Custom headers can be configured with the property in for Next.js projects, or it can be configured in for all other projects.

Alternatively, a Vercel Function can assign headers to the Response object.