diff --git a/docs/02-app/01-building-your-application/04-caching/index.mdx b/docs/02-app/01-building-your-application/04-caching/index.mdx index 5494a3d391082..7f7d66e669bfa 100644 --- a/docs/02-app/01-building-your-application/04-caching/index.mdx +++ b/docs/02-app/01-building-your-application/04-caching/index.mdx @@ -369,6 +369,8 @@ The cache is stored in the browser's temporary memory. Two factors determine how While a page refresh will clear **all** cached segments, the automatic invalidation period only affects the individual segment from the time it was prefetched. +> **Note**: There is [experimental support](/docs/app/api-reference/next-config-js/staleTimes) for configuring these values as of v14.2.0-canary.53. + ### Invalidation There are two ways you can invalidate the Router Cache: diff --git a/docs/02-app/02-api-reference/05-next-config-js/staleTimes.mdx b/docs/02-app/02-api-reference/05-next-config-js/staleTimes.mdx new file mode 100644 index 0000000000000..5e76c4c6803a6 --- /dev/null +++ b/docs/02-app/02-api-reference/05-next-config-js/staleTimes.mdx @@ -0,0 +1,42 @@ +--- +title: StaleTimes (experimental) +description: Learn how to override the invalidation time of the Client Router Cache. +--- + +> **Warning**: The `staleTimes` configuration is an experimental feature. This configuration strategy will likely change in the future. + +`staleTimes` is an experimental feature that allows configuring the [invalidation period](/docs/app/building-your-application/caching#duration-3) of the client router cache. + +This configuration option is available as of v14.2.0-canary.53. + +You can enable this experimental feature & provide custom revalidation times by setting the experimental `staleTimes` flag: + +```js filename="next.config.js" +/** @type {import('next').NextConfig} */ +const nextConfig = { + experimental: { + staleTimes: { + dynamic: 30, + static: 180, + }, + }, +} + +module.exports = nextConfig +``` + +The `static` and `dynamic` properties correspond with the time period (in seconds) based on different types of [link prefetching](/docs/app/api-reference/components/link#prefetch). + +- The `dynamic` property is used when the `prefetch` prop on `Link` is left unspecified. + - Default: 30 seconds +- The `static` property is used when the `prefetch` prop on `Link` is set to `true`, or when calling [`router.prefetch`](https://nextjs.org/docs/app/building-your-application/caching#routerprefetch). + - Default: 5 minutes + +> **Good to know:** +> +> - [Loading boundaries](/docs/app/api-reference/file-conventions/loading) are considered reusable for the `static` period defined in this configuration. +> - This doesn't disable partial rendering support, **meaning shared layouts won't automatically be refetched every navigation, only the new segment data.** +> - This doesn't change back/forward caching behavior to prevent layout shift & to prevent losing scroll position. +> - The different properties of this config refer to variable levels of "liveness" and are unrelated to whether the segment itself is opting into static or dynamic rendering. In other words, the current `static` default of 5 minutes suggests that data feels static by virtue of it being revalidated infrequently. + +You can learn more about the Client Router Cache [here](/docs/app/building-your-application/caching#router-cache).