How Next.js Cache Revalidation Works: Time-Based, On-Demand, Stale Data, and Expiry

In Next.js, cache revalidation is how cached data gets updated without dropping the cache. Under Cache Components there are two strategies: time-based revalidation with cacheLife, and on-demand revalidation with revalidateTag, updateTag, and revalidatePath. Most apps combine both.

A request first checks the cache. A fresh entry is served immediately, a stale entry is served while fresh data loads in the background, and an expired entry blocks until fresh data is ready.

Time-based revalidation

cacheLife sets a lifetime on a cached scope, and the framework refreshes the entry when that time passes. The lifetime has three timings.

• stale is how long the client trusts cached data without checking the server.
• revalidate is how often the server regenerates data in the background.
• expire is the maximum age before the next request must block for fresh data.

You pick a profile name or pass an object with the three values. For the full profile list, see cacheLife explained.

On-demand revalidation

When a mutation happens, invalidate the affected entries by tag or by path. Tag data with cacheTag, then expire it after the write.

typescript

// app/actions.ts
'use server'
 
import { updateTag } from 'next/cache'
 
export async function publishPost(id: string) {
  await db.posts.publish(id)
  updateTag(`post-${id}`)
  updateTag('posts')
}

This expires both the single post and the list, so the next request for either waits for fresh data. updateTag runs in Server Actions only, while revalidateTag works in Route Handlers too and refreshes in the background, serving stale content while it rebuilds. See revalidateTag vs updateTag for the choice.

Which strategy to use

Use time-based revalidation when content changes on a predictable schedule, such as an inventory feed that updates hourly. Use on-demand revalidation when content changes only when someone edits it, such as a blog post, and pair a long cacheLife with a tag so the page stays in the static shell between edits.

What to cache

Cache data that does not depend on the request and that you are comfortable serving for a set period. For CMS content that changes rarely, tag it and revalidate from a webhook instead of a timer, so unchanged content is not rebuilt for no reason.

In serverless environments, remember that in-memory entries may not survive between revalidations. Time-based and on-demand strategies are not exclusive, and a blog that tags its posts and also refreshes hourly combines both.

The practical rule is to tag entries where they are cached and invalidate them where the mutation happens, so the two halves stay close to the code that owns them.