cacheLife

The cacheLife function is used to set the cache lifetime of a function or component. It should be used alongside the use cache directive, and within the scope of the function or component.
To use cacheLife, first enable the cacheComponents flag in your next.config.js file:
cacheLife can only be used within a cache directive scope.
Add a cache directive (for example, use cache) at the file level or at the top of an async function or component.
cacheLife cannot be used at module scope. Calling it at the top level of a file will throw an error.
Next.js provides preset cache profiles that cover common caching needs. Each profile balances three factors:
Choose a profile based on how frequently your content changes:
Import cacheLife and pass a profile name:
The profile name tells Next.js how to cache the entire function's output. If you don't call cacheLife, the default profile is used. See preset cache profiles for timing details.
Cache profiles control caching behavior through three timing properties:
Client-side: How long the client can use cached data without checking the server.
During this time, the client-side router displays cached content immediately without any network request. After this period expires, the router must check with the server on the next navigation or request. This provides instant page loads from the client cache, but data may be outdated.
How often the server regenerates cached content in the background.
Maximum time before the server must regenerate cached content.
If you don't specify a profile, Next.js uses the default profile. We recommend explicitly setting a profile to make caching behavior clear.
The preset profiles map to familiar time periods (seconds, minutes, hours, days, weeks), alongside default and max. You can use these as they are, or redefine any of them, including default and max, in next.config.ts. The built-in names keep working with editor autocomplete.
Redefining a built-in is a supported pattern, but document it in your project so a call like cacheLife('hours') reflects the values you set, not the presets. The time-named profiles carry an intuitive expectation (days reads as roughly 24 hours), so redefining them is more likely to surprise a reader than redefining default or max, which don't imply a specific duration. An equally valid approach is to define your own custom profile rather than overloading a built-in name.
Redefining default also changes the lifetime applied when a use cache scope calls no cacheLife. The example below sets default to a one hour revalidate:
The cacheLife function's type signature is generated from next.config.ts during next dev, next build, or next typegen, so an overridden profile's editor autocomplete and JSDoc hint reflect the values you set, not the presets.
Define reusable cache profiles with your own names in next.config.ts:
The example above caches for 14 days, checks for updates daily, and expires the cache after 14 days. You can then reference this profile throughout your application by its name:
Any omitted properties in a custom profile inherit from the default profile. This also applies to inline profile objects passed directly to cacheLife().
For one-off cases, pass a profile object directly to cacheLife:
Inline profiles apply only to the specific function or component. For reusable configurations, define custom profiles in next.config.ts.
Using cacheLife({}) with an empty object applies the default profile values.
The stale property controls the Client Cache, not the Cache-Control header:
This 30-second minimum prevents prefetched data from expiring before users can click on links. It only applies to time-based expiration.
When you call revalidation functions from a Server Action (revalidateTag, revalidatePath, updateTag, or refresh), the entire client cache is immediately cleared, bypassing the stale time.
The stale property in cacheLife differs from staleTimes. While staleTimes is a global setting affecting all routes, cacheLife allows per-function or per-route configuration. Updating staleTimes.static also updates the stale value of the default cache profile.
A short cache lifetime changes where the cached content can be delivered from:
Of the presets, only seconds falls under any of these thresholds: its expire of 1 minute excludes it from prerenders.
This behavior allows you to mix static and dynamic content within the same page. Static parts are prerendered, while short-lived caches create boundaries where data is fetched at request time rather than build time. Use a <Suspense> boundary around dynamic caches to provide a fallback while content loads.
The simplest way to configure caching is using preset profiles. Choose one that matches your content's update pattern:
Define custom profiles when preset options don't match your requirements:
Then use these profiles throughout your application:
Use inline profiles when a specific function needs one-off caching behavior:
Apply caching to utility functions for granular control:
When you nest use cache directives (a cached function or component using another cached function or component), the outer cache's behavior depends on whether it has an explicit cacheLife.
The outer cache uses its own lifetime, regardless of inner cache lifetimes. When the outer cache hits, it returns the complete output including all nested data. An explicit cacheLife always takes precedence, whether it's longer or shorter than inner lifetimes.
If you don't call cacheLife in the outer cache, it uses the default profile (15 min revalidate). Inner caches with shorter lifetimes can reduce the outer cache's default lifetime. Inner caches with longer lifetimes cannot extend it beyond the default.