Next.js use cache, cacheLife and cacheTag: How One View Counter Rebuilt Every Page

Vercel's usage page told me this blog had used 2 h 32 min of function CPU in 30 days: 80% of everything on my account. It's a blog. The posts only change when I deploy.

The cause was one line near the top of my pages:

const stats = await getPostStats(); // read + comment counts, cached for 5 minutes

The counts were cached for 5 minutes. But the 5-minute timer didn't stay on the counts. Every page that showed them took it on, so every post, tag and series page went stale every 5 minutes and was rebuilt on the server the next time a reader or a crawler came by.

The mental model: a shared fridge#

Think of the server cache as one fridge that every visitor shares.

• "use cache" puts a result in the fridge. The next caller takes it out instead of cooking it again.
• cacheLife is the best-before sticker. After that date, the next visitor still gets the old dish while a fresh one cooks in the background.
• cacheTag is the name on the lid. You can throw out every box labelled comments at once, the moment the comments change.

A page is only as fresh as the shortest best-before date inside it.

How it works#

"use cache": store the result#

async function getPost(slug: string) {
  "use cache";
  return db.post.findUnique({ where: { slug } });
}

The arguments are part of the key, so getPost("a") and getPost("b") are separate boxes in the fridge. You can put "use cache" on a component too, and its rendered output is stored.

One rule: you can't read cookies() or headers() inside. Read them outside and pass the value in as an argument.

cacheLife: when it goes stale#

async function getExchangeRates() {
  "use cache";
  cacheLife("hours"); // or "minutes", "days", "max", or your own profile
  return fetch("https://api.example.com/rates").then((r) => r.json());
}

After the time is up, the next request still gets the old result straight away, and Next.js refreshes it in the background. Nobody waits.

The trap from my hook: a page's prerendered HTML is a cached thing too. If something inside it has a 5-minute life, the whole page gets a 5-minute life. That's how one counter set the clock for every page.

cacheTag: throw it out on demand#

async function getComments(slug: string) {
  "use cache";
  cacheLife("max");                         // no timer...
  cacheTag("comments", `comments:${slug}`); // ...just a name
  return db.comment.findMany({ where: { slug, approved: true } });
}

// when a comment is approved:
revalidateTag("comments", "max"); // route handler: serve old, refresh in background
updateTag(`comments:${slug}`);    // server action: the next request waits for fresh data

A timer is a guess about when data changes. A tag means you refresh exactly when it changes. My comment list used to sit on the 5-minute timer. Now it's "max" plus a tag, and new comments still show up straight away.

Which one to use#

Where TanStack Query fits#

They solve different problems, so you use both:

• Server cache (use cache) answers: "Don't hit the database for every visitor." One fridge, shared by everyone.
• TanStack Query answers: "Don't refetch for this visitor every time a component mounts." It's each visitor's own lunchbox in browser memory, with refetch on focus, polling, retries and optimistic updates.

The pattern I ended up with: render the page from server-cached data, and load live or per-user bits in the browser from a route handler that is itself cached.

// app/api/stats/route.ts — one shared, cached answer
export async function GET() {
  return Response.json(await getPostStats()); // getPostStats uses "use cache"
}

// in the browser — one request per visitor, shared by every component
const { data } = useQuery({
  queryKey: ["stats"],
  queryFn: () => fetch("/api/stats").then((r) => r.json()),
  staleTime: 30 * 60_000, // match the server's refresh time
});

When the user changes something, clear both layers: updateTag in the server action, then queryClient.invalidateQueries({ queryKey: [...] }) in the browser.

Honest stakes: after moving the counts into the browser, the build output for my post, tag and series pages went from refresh every 5m to refresh every 1d. Only /api/stats still refreshes on a timer. Most apps won't hit this exact bug, but any value read high up in a page can quietly set the clock for the whole page.

Say it in an interview#

"use cache marks a function or component whose result Next.js stores and reuses, keyed by its arguments. cacheLife sets how long it stays fresh and when it's refreshed in the background, and a page can't stay cached longer than the shortest life inside it. cacheTag names entries so I can invalidate them when the data changes, with revalidateTag or updateTag. TanStack Query is a separate, per-user cache in the browser: I use the server cache for shared data and TanStack Query for live or per-user data."

Cheat sheet#

TL;DR#

• "use cache" stores, cacheLife sets when it goes stale, cacheTag lets you clear it on demand.
• A page is only as fresh as the shortest-lived cache inside it. One 5-minute counter made all my pages refresh every 5 minutes.
• Prefer "cache forever + tag" for data you control, timers for data you don't.
• Use TanStack Query for per-user and live data, ideally fetching from a cached route.