cacheTag

Core Idea

cacheTag associa uma ou mais tags a uma entrada de cache criada com use cache, permitindo invalidar seletivamente esse cache sem afetar outros dados cacheados.

Key Concepts

• Pré-requisito: exige cacheComponents: true em next.config.js.
• cacheTag(...tags): aceita um ou mais valores string; deve ser chamado dentro do escopo use cache.
• Idempotência: aplicar a mesma tag várias vezes não tem efeito adicional.
• Limites: até 128 tags por chamada, cada uma com no máximo 256 caracteres; tags além do limite ou muito longas são descartadas com warning no console.
• updateTag: usado para cenários "read-your-own-writes" (ex. formulário), disponível só dentro de Server Functions; garante que a próxima leitura já reflita a mudança.
• revalidateTag: usado quando é aceitável servir dado stale enquanto revalida em background, ou de fora de Server Functions (ex. Route Handler).

Code Examples

import { cacheTag } from 'next/cache'

export async function getData() {
  'use cache'
  cacheTag('my-data')
  const res = await fetch('https://api.example.com/data')
  return res.json()
}

• O que demonstra: tag simples aplicada a uma função cacheada.

'use server'
import { updateTag } from 'next/cache'

export default async function submit() {
  await addPost()
  updateTag('my-data')
}

• O que demonstra: invalidação read-your-own-writes após uma mutação em Server Function.

async function getBookingsData() {
  'use cache'
  const response = await fetch(`https://api.example.com/bookings?type=${type}`)
  const data = await response.json()
  cacheTag('bookings-data', data.id)
  return data
}

• O que demonstra: criar tag dinâmica a partir de dado retornado pela própria função cacheada.

Anti-patterns

• Ultrapassar 128 tags ou 256 caracteres por tag: tags extras/longas são silenciosamente descartadas (com warning), não geram erro.

Key Takeaways

1. Use updateTag para mutações do usuário que precisam de leitura imediata e consistente (forms); use revalidateTag quando stale-enquanto-revalida for aceitável.
2. Múltiplas tags por entrada são suportadas em uma única chamada: cacheTag('tag-one', 'tag-two').
3. Tags podem ser derivadas de dados retornados pela própria função (ex. IDs), permitindo invalidação granular por item.

Connects To

• cacheLife: controla duração; cacheTag controla invalidação sob demanda, geralmente usados juntos.
• use cache: diretiva obrigatória para o escopo onde cacheTag funciona.
• revalidateTag / updateTag: funções que efetivamente disparam a invalidação da tag.