revalidateTag: invalidare i dati giusti

Un tag è un'etichetta che colleghi a una fetch, e revalidateTag invalida tutte le voci che portano quell'etichetta. Non è un refresh della pagina: è una cancellazione mirata che vale per l'intera applicazione.

Il giro completo

// lib/products.ts
export async function getProducts() {
  const res = await fetch("https://api.example.com/products", {
    next: { tags: ["products"], revalidate: 3600 },
  });
  return res.json();
}

L'etichetta vive nell'opzione next della fetch, non nella risposta. Ogni pagina che chiama getProducts condivide la stessa voce di cache e lo stesso tag: una sola invalidazione le copre tutte.

Dove chiamarlo

// app/api/revalidate/route.ts
import { revalidateTag } from "next/cache";
import { NextResponse } from "next/server";

const TAGS = new Set(["products", "orders"]);

export async function POST(request: Request) {
  const secret = request.headers.get("x-revalidate-secret");
  if (secret !== process.env.REVALIDATE_SECRET) {
    return NextResponse.json({ ok: false }, { status: 401 });
  }
  const tag = new URL(request.url).searchParams.get("tag") ?? "";
  if (!TAGS.has(tag)) {
    return NextResponse.json({ ok: false, reason: "unknown tag" }, { status: 400 });
  }
  revalidateTag(tag);
  return NextResponse.json({ ok: true, tag });
}

Il segreto e la allowlist non sono cerimonia: chi chiama quell'endpoint può svuotare la cache. Con pochi tag, la lista chiusa costa due righe e toglie la superficie di attacco.

La chiamata

curl -X POST "http://localhost:3000/api/revalidate?tag=products" \
  -H "x-revalidate-secret: $REVALIDATE_SECRET"

Tag, path o tempo

Gli errori tipici

• Chiamare revalidateTag durante il render di un server component: il runtime lo rifiuta.
• Mettere il tag sulla risposta invece che sulla fetch: l'etichetta va nell'opzione next.
• Assumere che il tag conosca la lingua: products vale per tutti i locale. Se il prezzo cambia solo in Italia, usa products-it.
• Dimenticare che Next.js 15 non mette in cache la fetch per default: senza next.revalidate o cache: "force-cache" il tag non ha effetto.

I casi in cui un dato vecchio si nota subito sono tabelle dati, statistiche e un blocco tabella.

I livelli di cache sono in i quattro livelli di cache; il comportamento HTTP in stale-while-revalidate e header di cache. Confronto: Next.js vs Vite.

Limite noto: il Data Cache vive nel processo che ha eseguito la fetch. Con due istanze, l'invalidazione su una non tocca l'altra: serve un cache handler condiviso o un TTL breve.