revalidateTag

Core Idea

Invalida dados cacheados sob demanda por tag, aplicando-se a todas as páginas que usam essa tag; ideal para conteúdo onde um pequeno delay na atualização é aceitável.

Key Concepts

• revalidateTag(tag, profile): tag string até 256 chars, case-sensitive. profile recomendado é "max" (stale-while-revalidate: serve conteúdo stale enquanto busca fresco em background) ou um profile customizado de cacheLife, ou objeto { expire }.
• Forma de um argumento deprecated: revalidateTag(tag) sem profile expira imediatamente (bloqueante) — migre para o formato com dois argumentos.
• Como taguear dados: via fetch(url, { next: { tags: ['posts'] } }) ou cacheTag('posts') dentro de função com 'use cache'.
• Contextos válidos: Server Functions e Route Handlers; não funciona em Client Components ou Proxy.

Code Examples

// app/actions.ts
'use server'
import { revalidateTag } from 'next/cache'

export default async function submit() {
  await addPost()
  revalidateTag('posts', 'max')
}

• O que demonstra: uso recomendado com profile="max" para stale-while-revalidate.

import { cacheTag } from 'next/cache'

async function getData() {
  'use cache'
  cacheTag('posts')
}

• O que demonstra: atribuir tag a uma função cacheada via cacheTag.

// Route Handler chamado por webhook externo que precisa de expiração imediata
revalidateTag(tag, { expire: 0 })

• O que demonstra: forçar expiração imediata (não apenas stale) quando um sistema externo exige dado atualizado no próximo request.

Reference Tables

Parameter	Type	Description
tag	string (máx 256 chars)	tag associada aos dados a invalidar
profile	string | { expire?: number }	"max" (recomendado) ou profile de cacheLife, ou objeto de expiração

Anti-patterns

• Usar a forma de um argumento (deprecated): funciona hoje só se erros de TypeScript forem suprimidos; pode ser removida no futuro.
• Chamar em Client Component ou Proxy: só funciona em ambiente server.
• Usar quando precisa de atualização imediata em Server Action: prefira updateTag para esse caso; revalidateTag é para delay aceitável.

Key Takeaways

1. profile="max" é a recomendação padrão: stale-while-revalidate, sem rajada de revalidações simultâneas.
2. A invalidação só acontece na próxima visita à página que usa a tag, não é instantânea globalmente.
3. Para expiração imediata vinda de webhook/sistema externo, use { expire: 0 }.

Connects To

• updateTag: expira dados imediatamente, use em Server Actions quando precisa de atualização instantânea.
• revalidatePath: invalida por path específico, não por tag entre páginas.
• cacheTag: atribui tags dentro de função 'use cache'.