How to Configure the Cache-Control Response Header in Vercel Projects

Sometimes, you may need to change the default value of the Cache-Control response header returned when a page of your deployment is requested. An example of that is when you want to set up Incremental Static Regeneration and you are not using Next.js. If you are using Next.js, it is recommended to use getStaticProps as explained here.

Overview

Before you get started, you should have:

• A Vercel Project deployed with at least one front-end page accessible using the framework of your choice.
• An understanding of configuring your project with a vercel.json file or a next.config.js file.
• An understanding of Edge Functions.

Let's say you have a page in your deployment called about. When this page is requested at yoursite.com/about, you would like to return the Cache-Control header with value s-maxage=1, stale-while-revalidate=59 so that Incremental Static Regeneration happens on this page for all subsequent requests based on the specified stale-while-revalidate value.

This guide shows three different methods of setting this Cache-Control header value on the about page.

Using the vercel.json file

This applies if your project is not based on Next.js.

Add the following code to your vercel.json file.

1
{
2
  "headers": [
3
    {
4
      "source": "/about.js",
5
      "headers": [
6
        {
7
          "key": "Cache-Control",
8
          "value": "s-maxage=1, stale-while-revalidate=59"
9
        }
10
      ]
11
    }
12
  ]
13
}

Next, deploy your project and go to yoursite.com/about in your web browser.

Finally, inspect the Network tab in the developer tools to view the response headers for this page and look for the Cache-Control value.

1
curl -v https://yoursite.com/about

Using the next.config.js file

This applies if your project uses Next.js

Add the following code to your next.config.js file.

1
/** @type {import('next').NextConfig} */
2
const nextConfig = {
3
  reactStrictMode: true,
4
  async headers() {
5
    return [
6
      {
7
        source: "/about",
8
        headers: [
9
          {
10
            key: "Cache-Control",
11
            value: "s-maxage=1, stale-while-revalidate=59",
12
          },
13
        ],
14
      },
15
    ];
16
  },
17
};
18

19
module.exports = nextConfig;

Next, deploy your project and go to yoursite.com/about in your web browser.

Finally, inspect the Network tab in the developer tools to view the response headers for this page and look for the Cache-Control value.

You can also use the curl command as explained above.

Using Edge Functions

This applies if your project uses the latest version of Next.js.

• Create a folder called about inside pages/.
• Move your about.js file to the about folder and rename it to index.js.
• Add a new file called handler.js in the /pages/api folder.
• Add the following code to your handler.js file:

1
import { NextResponse } from 'next/server';
2

3
export const config = {
4
  runtime: 'edge',
5
};
6

7
export default async function handler(req) {
8
  return NextResponse.json(
9
    { name: 'Mary Lamb' },
10
    {
11
      status: 200,
12
      headers: {
13
        'Cache-Control': 's-maxage=1, stale-while-revalidate=59',
14
      },
15
    },
16
  );
17
}

• Deploy your project and go to yoursite.com/about in your web browser.
• Inspect the Network tab in the developer tools to view the response headers for this page and look for the Cache-Control value.

You can also use the curl command as explained above.