cacheLife

Next.JS Use Cache

3 min read

Published Jul 3 2025

JavascriptNextJS

cacheLife documentation

A link to the official Next.JS documentation for cacheLife.

So in the documentation they refer to being able to set three parameters for the cacheLife: stale, revalidate and expire.

The aim of this is to be able to define anything up to the stale time as always returning cached data, after the stale time and up to the revalidate time then return the cached data but kick off a background process to revalidate the cache for the next request. Then between revalidate and expire, just return cached data, and then when the expire time is passed, always request new data and wait for the response.

However, on the current experimental version, the only time that is looked at is the revalidate time. So if you have 1 minute stale, 10 minutes revalidate and 20 minutes expire time, at the moment, up to 10 minutes will return cached data, and after 10 minutes it will make a fresh request for data.

There are a couple of ways that you can specify the cacheLife times. There are a number of predefined defaults that Next.JS provides, you can set your own, or override these defaults, or you can provide specific values for the three values directly.

The defaults defined in the documentation are:

Profile	stale	revalidate	expire	Description
`default`	5 minutes	15 minutes	1 year	Default profile, suitable for content that doesn't need frequent updates
`seconds`	0	1 second	1 second	For rapidly changing content requiring near real-time updates
`minutes`	5 minutes	1 minute	1 hour	For content that updates frequently within an hour
`hours`	5 minutes	1 hour	1 day	For content that updates daily but can be slightly stale
`days`	5 minutes	1 day	1 week	For content that updates weekly but can be a day old
`weeks`	5 minutes	1 week	30 days	For content that updates monthly but can be a week old
`max`	5 minutes	30 days	1 year	For very stable content that rarely needs updating

And you would use the defaults by specifying the profile name as a string:

cacheLife('days')

I personally like to provide the specific values though. So if we update our function from the last section to add cacheLife, we would do this:

import config from '@payload-config'

import { getPayload } from 'payload'

import { categories, category_images } from '@/payload-generated-schema'

import { eq } from '@payloadcms/db-postgres/drizzle'

import { unstable_cacheTag as cacheTag } from 'next/cache'

+import { unstable_cacheLife as cacheLife } from 'next/cache'

export const getCategory = async (slug: string) => {

'use cache'

+ cacheLife({

+ stale: 10 * 60 * 60 * 24, // 10 days

+ revalidate: 30 * 60 * 60 * 24, // 30 days

+ expire: 60 * 60 * 60 * 24, // 60 days

+ })

const payload = await getPayload({ config })

const cats = await payload.db.drizzle

.select({

id: categories.id,

slug: categories.slug,

title: categories.title,

description: categories.description,

image: {

id: category_images.id,

prefix: category_images.prefix,

filename: category_images.filename,

width: category_images.width,

height: category_images.height,

})

.from(categories)

.leftJoin(category_images, eq(category_images.id, categories.image))

.where(eq(categories.slug, slug))

cacheTag('categories', 'category:' + cats[0].id)

return cats[0] || undefined

}

The times are specified in seconds, so you can put the whole total number, but its much easier to read if you do it as a calculation like above.

At the moment, this would just cache the result for 30 days though. The 10 and 60 day settings are not being used yet.

So thats it, with not much effort you can specify that data should be cached, how long for and add tags to easily revalidate the cache when needed. Even though this is still experimental, it is very stable from what i have found and i'm using it in production just fine.