diff --git a/docs/02-app/02-api-reference/05-next-config-js/headers.mdx b/docs/02-app/02-api-reference/05-next-config-js/headers.mdx index d8ed4ee398311..cdc99cf789b10 100644 --- a/docs/02-app/02-api-reference/05-next-config-js/headers.mdx +++ b/docs/02-app/02-api-reference/05-next-config-js/headers.mdx @@ -388,7 +388,9 @@ module.exports = { ## Cache-Control -You cannot set `Cache-Control` headers in `next.config.js` for pages or assets, as these headers will be overwritten in production to ensure that responses and static assets are cached effectively. +Next.js sets the `Cache-Control` header of `public, max-age=31536000, immutable` for truly immutable assets. It cannot be overridden. These immutable files contain a SHA-hash in the file name, so they can be safely cached indefinitely. For example, [Static Image Imports](/docs/app/building-your-application/optimizing/images#local-images). You cannot set `Cache-Control` headers in `next.config.js` for these assets. + +However, you can set `Cache-Control` headers for other responses or data. @@ -400,7 +402,7 @@ Learn more about [caching](/docs/app/building-your-application/caching) with the If you need to revalidate the cache of a page that has been [statically generated](/docs/pages/building-your-application/rendering/static-site-generation), you can do so by setting the `revalidate` prop in the page's [`getStaticProps`](/docs/pages/building-your-application/data-fetching/get-static-props) function. -You can set the `Cache-Control` header in your [API Routes](/docs/pages/building-your-application/routing/api-routes) by using the `res.setHeader` method: +To cache the response from an [API Route](/docs/pages/building-your-application/routing/api-routes), you can use `res.setHeader`: ```ts filename="pages/api/hello.ts" switcher import type { NextApiRequest, NextApiResponse } from 'next' @@ -425,6 +427,50 @@ export default function handler(req, res) { } ``` +You can also use caching headers (`Cache-Control`) inside `getServerSideProps` to cache dynamic responses. For example, using [`stale-while-revalidate`](https://web.dev/stale-while-revalidate/). + +```ts filename="pages/index.tsx" switcher +import { GetStaticProps, GetStaticPaths, GetServerSideProps } from 'next' + +// This value is considered fresh for ten seconds (s-maxage=10). +// If a request is repeated within the next 10 seconds, the previously +// cached value will still be fresh. If the request is repeated before 59 seconds, +// the cached value will be stale but still render (stale-while-revalidate=59). +// +// In the background, a revalidation request will be made to populate the cache +// with a fresh value. If you refresh the page, you will see the new value. +export const getServerSideProps = (async (context) => { + context.res.setHeader( + 'Cache-Control', + 'public, s-maxage=10, stale-while-revalidate=59' + ) + + return { + props: {}, + } +}) satisfies GetServerSideProps +``` + +```js filename="pages/index.js" switcher +// This value is considered fresh for ten seconds (s-maxage=10). +// If a request is repeated within the next 10 seconds, the previously +// cached value will still be fresh. If the request is repeated before 59 seconds, +// the cached value will be stale but still render (stale-while-revalidate=59). +// +// In the background, a revalidation request will be made to populate the cache +// with a fresh value. If you refresh the page, you will see the new value. +export async function getServerSideProps({ req, res }) { + res.setHeader( + 'Cache-Control', + 'public, s-maxage=10, stale-while-revalidate=59' + ) + + return { + props: {}, + } +} +``` + ## Options