revalidateTag: invalidating the right data

A tag is a label you attach to a fetch, and revalidateTag invalidates every entry carrying that label. It is not a page refresh: it is a targeted deletion that applies to the whole application.

The full loop

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

The label lives in the next option of the fetch, not in the response. Every page that calls getProducts shares one cache entry and one tag: a single invalidation covers them all.

Where to call it

// 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 });
}

The secret and the allowlist are not ceremony: whoever calls that endpoint can empty the cache. With few tags, a closed list costs two lines and removes the attack surface.

The call

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

Tag, path or time

The usual mistakes

• Calling revalidateTag during the render of a server component: the runtime rejects it.
• Putting the tag on the response instead of the fetch: the label belongs in the next option.
• Assuming the tag knows the language: products covers every locale. If the price changes only in Italy, use products-it.
• Forgetting that Next.js 15 does not cache fetch by default: without next.revalidate or cache: "force-cache" the tag has no effect.

The cases where stale data shows immediately are data tables, stats and a table block.

The cache levels are in the four cache layers; HTTP behaviour in stale-while-revalidate and cache headers. Comparison: Next.js vs Vite.

Known limitation: the Data Cache lives in the process that ran the fetch. With two instances, invalidating on one leaves the other untouched: you need a shared cache handler or a short TTL.