Skip to content
App Router...next.config.js OptionsstaleTimes (experimental)

staleTimes (experimental)

Warning: The staleTimes configuration is an experimental feature. This configuration strategy will likely change in the future.

staleTimes is an experimental feature that enables caching of page segments in the client-side router cache.

You can enable this experimental feature and provide custom revalidation times by setting the experimental staleTimes flag:

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.

  • The dynamic property is used when the prefetch prop on Link is left unspecified or is set to false.
    • Default: 0 seconds (not cached)
  • The static property is used when the prefetch prop on Link is set to true, or when calling router.prefetch.
    • Default: 5 minutes

Good to know:

  • Loading boundaries are considered reusable for the static period defined in this configuration.
  • This doesn't affect partial rendering, meaning shared layouts won't automatically be refetched on every navigation, only the page segment that changes.
  • This doesn't change back/forward caching behavior to prevent layout shift and to prevent losing the browser 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.

Version History

VersionChanges
v15.0.0staleTimes enables and configures the duration for page segments
v14.2.0experimental staleTimes introduced