Time-based revalidation
A page or component needs scheduled freshness without manual invalidation.
Next.js 16+ · Function
unstable_cacheLife
unstable_cacheLife assigns a lifetime profile to cached functions or components used with use cache. It is deprecated in Next.js 16; use the stable cacheLife API instead.
- Since
- v16.0.0 (the stable cacheLife API replaced unstable_cacheLif
How it works
Import the experimental alias from next/cache, then call it inside a function or component that uses the use cache directive. The selected named profile controls staleness, server revalidation, and eventual expiration; custom profiles can be configured in next.config.ts. In Next.js 16, the unprefixed cacheLife API is stable and the unstable_ alias is deprecated.
Syntax
unstable_cacheLife(profile?: string | CacheLifeConfig): voidParameters
| Name | Type | Description |
|---|---|---|
profile | string | CacheLifeConfig | A built-in profile name or a custom profile name/configuration that defines cache timing. |
Returns
void
Key points
- It assigns a cache lifetime to the function or component containing the cache directive.
- Built-in profiles represent different freshness intervals and can be selected by name.
- Omitting the profile causes Next.js to apply the
defaultprofile automatically. - A custom profile is named and defines separate stale, refresh, and maximum-expiration values.
Common mistakes
- For Next.js 16, prefer the stable
cacheLifeimport because the experimental alias is deprecated.
Example: Apply an hourly cache profile
import { unstable_cacheLife as cacheLife } from 'next/cache'
export default async function Page() {
'use cache'
cacheLife('hours')
return <div>Cached page</div>
}Enables Cache Components, marks the page for caching, and assigns the built-in hourly cache profile.
When to use it
Reusable custom profiles
Several cached functions need the same organization-specific timing policy.
API migration
An existing Next.js 15 application is being updated to Next.js 16.
Interview questions
QWhat does unstable_cacheLife control?
unstable_cacheLife sets the lifetime of a cached function or component. It is used inside a use cache scope and accepts a named profile or custom profile configuration.
Follow-up: How would you migrate this code in Next.js 16? Replace the aliased unstable_cacheLife import with cacheLife from next/cache, because the API was stabilized.
QWhat happens when no cache profile is specified?
A named profile supplies timing values for stale data, server revalidation, and expiration. If no profile is supplied, Next.js uses the default profile.
Follow-up: How can an application define its own timing policy? Add a named profile with stale, revalidate, and expire properties to the cacheLife option in next.config.ts.
QWhich cache profiles can be passed to the function?
The function can use built-in profiles such as seconds, minutes, hours, days, weeks, and max. A profile name is passed as a string, for example cacheLife('hours').
Follow-up: When should a custom profile be used? Use one when the built-in time scales do not match the application's freshness and expiration requirements.
Related
cacheLifeuse cachecacheComponentscacheTagunstable_cache