UndieGravity LogoUndiegravity

Next.js Caching Explained Simply: revalidate, use cache, and Tags

How caching works in Next.js 16: static pages, time-based revalidation, the use cache directive, and tag invalidation with revalidateTag and updateTag.

By UndieGravity, , 2 min read

Caching is where most Next.js confusion comes from, mostly because the defaults changed between versions. The good news: in Next.js 16 the model is explicit. Nothing is cached unless you ask for it, and there are only a few tools to learn.

Start with the question: how fresh does this data need to be?

  • Never changes after deploy (an about page, a blog post): fully static.
  • Changes a few times a day (a product catalog): static, refreshed on a timer or when the data changes.
  • Different for every visitor (a cart, a dashboard): rendered per request, not cached.

Pick the strategy per page or per piece of data, not for the whole site.

Static by default when nothing is dynamic

A route that reads no cookies, headers, or search params, and fetches no uncached data, is prerendered at build time. You can see this in the next build output, where each route is marked static or dynamic.

Time-based revalidation

Export revalidate from a page or layout to rebuild it in the background at most every N seconds. Visitors keep getting the cached page while the new one is generated.

// app/templates/page.tsx
export const revalidate = 60; // seconds

You can also set it per request: fetch(url, { next: { revalidate: 60, tags: ["templates"] } }).

On-demand revalidation with tags

Waiting 60 seconds is fine for most sites, but when an editor publishes something you often want it live right away. Tag the data when you fetch it, then invalidate the tag when it changes.

import { revalidateTag } from "next/cache";

// In a route handler called by your CMS or backend webhook
revalidateTag("templates", "max");

In Next.js 16 revalidateTag takes a cache profile as its second argument. With "max", visitors are served the old version while the new one is built (stale while revalidate). The one-argument form is deprecated.

updateTag for read-your-own-writes

When a user saves something and must see the change immediately, for example after editing their profile, call updateTag inside the Server Action. It expires the cache right away instead of serving a stale copy first. It only works in Server Actions.

The use cache directive

With cacheComponents: true in next.config.ts, you mark cached functions or components with the "use cache" directive and control them with cacheLife and cacheTag. This enables Partial Prerendering: a static shell is served instantly while dynamic parts stream in.

import { cacheLife, cacheTag } from "next/cache";

export async function getTemplates() {
  "use cache";
  cacheLife("hours");
  cacheTag("templates");
  const res = await fetch("https://api.example.com/templates");
  return res.json();
}

Turning on cacheComponents is not a one-line change: uncached data outside a <Suspense> boundary becomes a build error. Enable it on a branch and fix the reported routes one by one.

Debugging a page that will not update

  1. Check the build output: is the route static or dynamic?
  2. Check the revalidate value on the page and its layouts; the lowest one wins.
  3. Check that the tag you revalidate matches the tag on the fetch exactly.
  4. Remember the browser and CDN may cache too; test in a private window.

Keep reading

Next.js

Next.js 16: What Changed and How to Upgrade

Next.js 16 makes Turbopack the default, renames middleware to proxy, requires async request APIs, and changes caching. Here is what to update first.

, 2 min read