Pular para o conteúdo
Documentação do Next.js PT-BR
Esta página ainda está em inglês. A tradução ainda não foi feita; o conteúdo abaixo é o original de nextjs.org.

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: updateTag immediately 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.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

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

app/actions.ts
'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}`)
}

Error when used outside Server Actions

app/api/posts/route.ts
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