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. 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

The revalidation behavior depends on whether you provide the second argument:

• With profile="max" (recommended): The tag entry is marked as stale, and the next time a resource with that tag is visited, it will use stale-while-revalidate semantics. This means the stale content is served while fresh content is fetched in the background.
• With a custom cache life profile: For advanced usage, you can specify any cache life profile that your application has defined, allowing for custom revalidation behaviors tailored to your specific caching requirements.
• Without the second argument (deprecated): The tag entry is expired immediately, and the next request to that resource will be a blocking revalidate/cache miss. This behavior is now deprecated, and you should either use profile="max" or migrate to updateTag.

Parameters

revalidateTag(tag: string, profile?: string): void;

• tag: A string representing the cache tag associated with the data you want to revalidate. Must not exceed 256 characters. This value is case-sensitive.
• profile: A string that specifies the revalidation behavior. The recommended value is "max" which provides stale-while-revalidate semantics. For advanced usage, this can be configured to any cache life profile that your application defines.

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

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',
  })
}