Revalidating

Revalidation is the process of updating cached data. It lets you keep serving fast, cached responses while ensuring content stays fresh. There are two strategies:

• Time-based revalidation: Automatically refresh cached data after a set duration using cacheLife.
• On-demand revalidation: Manually invalidate cached data after a mutation using revalidateTag, updateTag, or revalidatePath.

cacheLife

cacheLife controls how long cached data remains valid. Use it inside a use cache scope to set the cache lifetime.

import { cacheLife } from 'next/cache'
 
export async function getProducts() {
  'use cache'
  cacheLife('hours')
  return db.query('SELECT * FROM products')
}

cacheLife accepts a profile name or a custom configuration object:

For fine-grained control, pass an object:

'use cache'
cacheLife({
  stale: 3600, // 1 hour until considered stale
  revalidate: 7200, // 2 hours until revalidated
  expire: 86400, // 1 day until expired
})

See the cacheLife API reference for all profiles and custom configuration options.

cacheTag

cacheTag lets you tag cached data so it can be invalidated on-demand. Use it inside a use cache scope:

import { cacheTag } from 'next/cache'
 
export async function getProducts() {
  'use cache'
  cacheTag('products')
  return db.query('SELECT * FROM products')
}

Once tagged, invalidate the cache using revalidateTag or updateTag.

See the cacheTag API reference to learn more.

revalidateTag

revalidateTag invalidates cache entries by tag using stale-while-revalidate semantics — stale content is served immediately while fresh content loads in the background. This is ideal for content where a slight delay in updates is acceptable, like blog posts or product catalogs.

import { revalidateTag } from 'next/cache'
 
export async function updateUser(id: string) {
  // Mutate data
  revalidateTag('user', 'max') // Recommended: stale-while-revalidate
}

You can reuse the same tag in multiple functions to revalidate them all at once. Call revalidateTag in a Server Action or Route Handler.

See the revalidateTag API reference to learn more.

updateTag

updateTag immediately expires cached data for read-your-own-writes scenarios — the user sees their change right away instead of stale content. Unlike revalidateTag, it can only be used in Server Actions.

import { updateTag } from 'next/cache'
import { redirect } from 'next/navigation'
 
export async function createPost(formData: FormData) {
  const post = await db.post.create({
    data: {
      title: formData.get('title'),
      content: formData.get('content'),
    },
  })
 
  updateTag('posts')
  redirect(`/posts/${post.id}`)
}

See the updateTag API reference to learn more.

revalidatePath

revalidatePath invalidates all cached data for a specific route path. Use it when you want to revalidate a route without knowing which tags are associated with it.

import { revalidatePath } from 'next/cache'
 
export async function updateUser(id: string) {
  // Mutate data
  revalidatePath('/profile')
}

See the revalidatePath API reference to learn more.

What should I cache?

Cache data that doesn't depend on runtime data and that you're OK serving from cache for a period of time. Use use cache with cacheLife to describe that behavior.

For content management systems with update mechanisms, use tags with longer cache durations and rely on revalidateTag to refresh content when it actually changes, rather than expiring the cache preemptively.