Skip to content
Last updated on February 13, 2023
3 min read

Caching Serverless Function Responses

The Vercel Edge Network cache is active for all deployments and domains on your account and caches your content at the edge to serve data to your users as fast as possible.

The Vercel Edge Network cache is available for all of our pricing plans (including the Hobby plan) and can be activated for Serverless Functions (including SSR) by providing Cache-Control headers.

If Cache-Control headers are provided, responses will be cached in the region it’s requested from.

What is Cached?

In order for responses to be cached with the Cache-Control header by the Vercel Edge Network cache for the requested path, 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 set-cookie header
  • Response must not contain the private, no-cache or no-store directives in the Cache-Control header

Cache Control

To control how responses are cached, you can provide a Cache-Control header in the response from your Serverless Function. It can include any of the following directives, separated by a comma:

  • s-maxage=N
  • max-age=N, public
  • max-age=N, immutable
Note: Where N is the number of seconds the response should be cached for.

As an example, you can set the Cache-Control header in your Next.js API Routes by using the response.setHeader method:

pages/api/user.js
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.

Note: Please note that Cache-Control headers cannot be set using next.config.js or vercel.json (for other frameworks) files.

Recommended Cache-Control

We recommend that you set your cache to have max-age=0, s-maxage=86400, with changing 86400 to the amount of seconds you want your response to be cached for.

This recommendation will tell browsers not to cache and let our edge cache the responses and invalidate when your deployments update, so you never have to worry about stale content.

stale-while-revalidate

The Vercel Edge Network cache 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 the Vercel Edge Network cache 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 cache to expire

In both cases, we recommend using:

set-cache-control
Cache-Control: s-maxage=1, stale-while-revalidate

Which tells the Vercel Edge Network cache: serve from cache, but update it, if requested after 1 second.

When the Vercel Edge Network cache receives a request with Pragma: no-cache (such as when the browser devtools are open), it will revalidate any stale resource synchronously, instead of in the background.

Cache Invalidation and Purging

Every time you deploy with a custom domain, the cache for that domain is purged. This means that users will never see content from a previous deployment on your custom domain and there is no need to invalidate it manually when deploying.