āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š nextjs/app/api-reference/functions/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.
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.
The revalidation behavior depends on whether you provide the second argument:
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.profile="max" or migrate to updateTag.Good to know: When using
profile="max",revalidateTagmarks tagged data as stale, but fresh data is only fetched when pages using that tag are next visited. This means callingrevalidateTagwill not immediately trigger many revalidations at once. The invalidation only happens when any page using that tag is next visited.
revalidateTag(tag: string, profile: string | { expire?: number }): 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, or any of the other default or custom profiles defined in cacheLife. Alternatively, you can pass an object with an expire property for custom expiration behavior.Tags must first be assigned to cached data. You can do this in two ways:
next.tags option with fetch for caching external API requests:fetch(url, { next: { tags: ['posts'] } })
cacheTag inside cached functions or components with the 'use cache' directive:import { cacheTag } from 'next/cache'
async function getData() {
'use cache'
cacheTag('posts')
// ...
}
Good to know: The single-argument form
revalidateTag(tag)is deprecated. It currently works if TypeScript errors are suppressed, but this behavior may be removed in a future version. Update to the two-argument signature.
revalidateTag does not return a value.
revalidatePathrevalidateTag invalidates data with specific tags across all pages that use those tags, while revalidatePath invalidates specific page or layout paths.
Good to know: These functions serve different purposes and may need to be used together for comprehensive data consistency. For detailed examples and considerations, see relationship with revalidateTag and updateTag for more information.
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.
'use server'
import { revalidateTag } from 'next/cache'
export default async function submit() {
await addPost()
revalidateTag('posts', 'max')
}
'use server'
import { revalidateTag } from 'next/cache'
export default async function submit() {
await addPost()
revalidateTag('posts', 'max')
}
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',
})
}
import { revalidateTag } from 'next/cache'
export async function GET(request) {
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',
})
}
Good to know: For webhooks or third-party services that need immediate expiration, you can pass
{ expire: 0 }as the second argument:revalidateTag(tag, { expire: 0 }). This pattern is necessary when external systems call your Route Handlers and require data to expire immediately. For all other cases, it's recommended to useupdateTagin Server Actions for immediate updates instead.
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā