revalidateTag

revalidateTag allows you to invalidate cached data on-demand for a specific cache tag.

This function is ideal for content where a slight delay in updates is acceptable, such as blog posts, product catalogs, or documentation. With the recommended max profile, users receive stale content while fresh data loads in the background.

Usage

revalidateTag can be called in Server Functions and Route Handlers.

revalidateTag cannot be called in Client Components or Proxy, as it only works in server environments.

Revalidation Behavior

Calling revalidateTag marks the tagged data as stale. The next request for that data kicks off a revalidation and is served stale content while it runs, using stale-while-revalidate semantics. The second argument sets how long stale content may be served. Past that, a request blocks until the revalidation completes.

• profile="max" (recommended): A one year window, long enough that requests are always served stale content while the revalidation runs.
• Another profile, or an object: Any other default or custom profile defined in cacheLife, or an object with an expire property, when you want a different window.
• { expire: 0 }: Stale content is never served, so the next request is a blocking revalidate/cache miss. Use it when the caller needs the data gone immediately and you cannot use updateTag.
• No second argument (deprecated): Behaves like { expire: 0 }. Migrate to updateTag in Server Actions, or profile="max".

The profile sets the point past which data correctness is more important than being fast.

Parameters

revalidateTag(tag: string, profile: string | { expire?: number }): void;

• tag: A string representing the cache tag associated with the data you want to revalidate. Tags are case-sensitive and must not exceed 256 characters. A tag that exceeds the limit is never assigned to cached data, so revalidating it does nothing.
• profile: How long stale content may be served, see Revalidation Behavior. The recommended value is "max". Any other default or custom profile defined in cacheLife is also accepted, and only its expire is read. You can also pass an object with an expire property, in seconds.

Tags must first be assigned to cached data. You can do this in two ways:

• Using the next.tags option with fetch for caching external API requests:

fetch(url, { next: { tags: ['posts'] } })

• Using cacheTag inside cached functions or components with the 'use cache' directive:

import { cacheTag } from 'next/cache'
 
async function getData() {
  'use cache'
  cacheTag('posts')
  // ...
}

Returns

revalidateTag does not return a value.

Relationship with revalidatePath

revalidateTag invalidates data with specific tags across all pages that use those tags, while revalidatePath invalidates specific page or layout paths.

Examples

The following examples demonstrate how to use revalidateTag in different contexts. In both cases, we're using profile="max" to mark data as stale and use stale-while-revalidate semantics, which is the recommended approach for most use cases.

Server Action

'use server'
 
import { revalidateTag } from 'next/cache'
 
export default async function submit() {
  await addPost()
  revalidateTag('posts', 'max')
}

Route Handler

import type { NextRequest } from 'next/server'
import { revalidateTag } from 'next/cache'
 
export async function GET(request: NextRequest) {
  const tag = request.nextUrl.searchParams.get('tag')
 
  if (tag) {
    revalidateTag(tag, 'max')
    return Response.json({ revalidated: true, now: Date.now() })
  }
 
  return Response.json({
    revalidated: false,
    now: Date.now(),
    message: 'Missing tag to revalidate',
  })
}

When the invalidation comes from outside a Server Action, for example a webhook or another service calling a Route Handler, updateTag is not available. Pass { expire: 0 } to expire the data immediately:

revalidateTag(tag, { expire: 0 })