unstable_expireTag

unstable_expireTag allows you to purge cached data on-demand for a specific cache tag.

Good to know:

• unstable_expireTag is available in both Node.js and Edge runtimes.
• unstable_expireTag only invalidates the cache when the path is next visited. This means calling unstable_expireTag with a dynamic route segment will not immediately trigger many expirations at once. The invalidation only happens when the path is next visited.

Reference

Parameters

unstable_expireTag(...tags: string[]): void;

• tags: String arguments representing the cache tags associated with the data you want to revalidate. Must be less than or equal to 256 characters each. This value is case-sensitive.

You can add tags to fetch as follows:

fetch(url, { next: { tags: [...] } });

Returns

unstable_expireTag does not return a value.

Examples

Server Action

You can invoke unstable_expireTag in a Server Action:

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

Route Handler

You can invoke unstable_expireTag in a Route Handler:

import type { NextRequest } from 'next/server'
import { unstable_expireTag } from 'next/cache'
 
export async function GET(request: NextRequest) {
  const tag = request.nextUrl.searchParams.get('tag')
  unstable_expireTag(tag)
  return Response.json({ revalidated: true, now: Date.now() })
}