āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š nextjs/app/api-reference/functions/updateTag ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
updateTag allows you to update cached data on-demand for a specific cache tag from within Server Actions.
This function is designed for read-your-own-writes scenarios, where a user makes a change (like creating a post), and the UI immediately shows the change, rather than stale data.
updateTag can only be called from within Server Actions. It cannot be used in Route Handlers, Client Components, or any other context.
If you need to invalidate cache tags in Route Handlers or other contexts, use revalidateTag instead.
Good to know:
updateTagimmediately expires the cached data for the specified tag. The next request will wait to fetch fresh data rather than serving stale content from the cache, ensuring users see their changes immediately.
updateTag(tag: string): void;
tag: A string representing the cache tag associated with the data you want to update. Must not exceed 256 characters. This value is case-sensitive.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')
// ...
}
updateTag does not return a value.
While both updateTag and revalidateTag invalidate cached data, they serve different purposes:
updateTag:
revalidateTag:
profile="max" (recommended): Serves cached data while fetching fresh data in the background (stale-while-revalidate)updateTag'use server'
import { updateTag } from 'next/cache'
import { redirect } from 'next/navigation'
export async function createPost(formData: FormData) {
const title = formData.get('title')
const content = formData.get('content')
// Create the post in your database
const post = await db.post.create({
data: { title, content },
})
// Invalidate cache tags so the new post is immediately visible
// 'posts' tag: affects any page that displays a list of posts
updateTag('posts')
// 'post-{id}' tag: affects the individual post detail page
updateTag(`post-${post.id}`)
// Redirect to the new post - user will see fresh data, not cached
redirect(`/posts/${post.id}`)
}
'use server'
import { updateTag } from 'next/cache'
import { redirect } from 'next/navigation'
export async function createPost(formData) {
const title = formData.get('title')
const content = formData.get('content')
// Create the post in your database
const post = await db.post.create({
data: { title, content },
})
// Invalidate cache tags so the new post is immediately visible
// 'posts' tag: affects any page that displays a list of posts
updateTag('posts')
// 'post-{id}' tag: affects the individual post detail page
updateTag(`post-${post.id}`)
// Redirect to the new post - user will see fresh data, not cached
redirect(`/posts/${post.id}`)
}
import { updateTag } from 'next/cache'
export async function POST() {
// This will throw an error
updateTag('posts')
// Error: updateTag can only be called from within a Server Action
// Use revalidateTag instead in Route Handlers
revalidateTag('posts', 'max')
}
Use updateTag when:
Use revalidateTag instead when:
revalidateTag - For invalidating tags in Route HandlersrevalidatePath - For invalidating specific pathsā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā