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.
Usage
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.
Client cache behavior
When a Server Action calls updateTag, Next.js re-renders the current route and sends the updated UI in the action's response, whether or not the route uses the tag. Uncached data is fetched again, and server-side cached data without the tag is reused.
The client uses the action's response to re-render the current route and clears every prefetched route and the route data kept for back/forward navigation, not only routes that use the tag. Eligible visible links may prefetch again as a result. Pages preserved by Activity stay mounted and keep their React state. Their server data refreshes when you navigate back to them.
revalidateTag has the same effects in a Server Action when its profile resolves to expire: 0. That covers { expire: 0 }, a named profile with expire: 0, and the deprecated single-argument form. With a nonzero expire, such as 'max', it marks tagged data as stale and skips the re-render and the client cache clearing. Other calls in the action, such as refresh, can still trigger a re-render.
Parameters
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:
- Using the
next.tagsoption withfetchfor caching external API requests:
fetch(url, { next: { tags: ['posts'] } })- Using
cacheTaginside cached functions or components with the'use cache'directive:
import { cacheTag } from 'next/cache'
async function getData() {
'use cache'
cacheTag('posts')
// ...
}Returns
updateTag does not return a value.
Differences from revalidateTag
While both updateTag and revalidateTag invalidate cached data, they serve different purposes:
-
updateTag:- Can only be used in Server Actions
- Next request waits for fresh data (no stale content served)
- Designed for read-your-own-writes scenarios
-
revalidateTag:- Can be used in Server Actions and Route Handlers
- With
profile="max"(recommended): Serves cached data while fetching fresh data in the background (stale-while-revalidate) - With custom profile: Can be configured to any cache life profile for advanced usage
- Without profile: legacy behavior which is equivalent to
updateTag
Examples
Server Action with Read-Your-Own-Writes
'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}`)
}Error when used outside Server Actions
import { revalidateTag, 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')
}When to use updateTag
Use updateTag when:
- You're in a Server Action
- You need immediate cache invalidation for read-your-own-writes
- You want to ensure the next request sees updated data
Use revalidateTag instead when:
- You're in a Route Handler or other non-action context
- You want stale-while-revalidate semantics
- You're building a webhook or API endpoint for cache invalidation
Related
revalidateTag- For invalidating tags in Route HandlersrevalidatePath- For invalidating specific paths