Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Next.js Data Fetching: Caching, revalidate, and Tag-Based Invalidation

Next.js 15 stopped caching fetch by default. How request memoization, the data cache, and the route cache interact, and when to invalidate by tag instead of by clock.

~4 min readNext.js
#Next.js#Caching#Data Fetching#App Router
3D illustration of stacked cache slabs invalidated by tag chips beside a revalidate clock dial

Quick Summary

In the App Router, fetch is extended with caching controls, and the default changed in Next.js 15: a fetch with no options is no-store — not cached. That single change explains most "my data is fresh in v15 but was stale in v14" and its inverse. Caching is opt-in with cache: "force-cache", a next: { revalidate: n } window, or a next: { tags: [...] } tag.

Three layers interact. The request memoization of a fetch with the same URL and options inside one render pass is automatic and unavoidable. The data cache persists across requests on the server, keyed by URL and options, governed by cache/revalidate/tags. The full route cache stores the rendered HTML and RSC payload for static routes, and is invalidated by revalidatePath or a tag.

revalidateTag and revalidatePath are on-demand invalidation: call them from a Server Action or route handler after a mutation, and the next request re-renders. revalidate: 0 is effectively no-store; revalidate: false caches forever. Reading cookies() or headers() in a route makes it dynamic regardless of what the fetch calls asked for.

Basic Syntax & Core Signatures

tsx
// Cached until revalidated by tag, or by the window const res = await fetch("https://api.example.com/products", { next: { revalidate: 60, tags: ["products"] }, }); // Never cached const live = await fetch("https://api.example.com/stock", { cache: "no-store" }); // Cached indefinitely (until deploy or invalidation) const config = await fetch("https://api.example.com/config", { cache: "force-cache" });
tsx
// Route segment config: a floor/ceiling for the whole segment export const revalidate = 300; // default revalidate for fetches in this segment export const dynamic = "force-dynamic"; // opt out of the full route cache export const fetchCache = "force-no-store";
tsx
// Invalidation from a Server Action "use server"; import { revalidateTag, revalidatePath } from "next/cache"; export async function updateProduct(id: string, data: FormData) { await db.product.update({ where: { id }, data: { name: String(data.get("name")) } }); revalidateTag("products"); // every fetch tagged "products" is stale revalidatePath(`/products/${id}`); // and the rendered route too }
tsx
// Non-fetch data: unstable_cache wraps any async function import { unstable_cache } from "next/cache"; export const getProducts = unstable_cache( async () => db.product.findMany(), ["products"], { revalidate: 60, tags: ["products"] } );

Key Comparison Table

OptionCachesLifetimeInvalidate with
cache: "no-store" (default in 15)No——
cache: "force-cache"YesUntil deployrevalidateTag, revalidatePath
next: { revalidate: 60 }Yes60s stale-while-revalidateTag or path, or the window
next: { revalidate: false }YesIndefiniteTag or path
next: { revalidate: 0 }No——
unstable_cacheYes, for any functionPer optionsrevalidateTag
ConceptScopeCleared by
Request memoizationOne render passNothing (by design)
Data cacheServer, across requestsrevalidateTag/Path, window
Full route cacheRendered HTML/RSCrevalidatePath, deploy, window
Router cache (client)Browser sessionNavigation, router.refresh()
SymptomMeaning
Fresh data in dev, stale in productionA fetch earlier in the tree cached it, or the route cache
revalidateTag seems ignoredThe fetch has no matching tag, or the route is cached at another layer
Data never caches in v15Default is no-store; opt in explicitly

Practical Edge Cases & Deep Dives

1. The v14 → v15 default, and the code that depends on it

In Next.js 14 a bare fetch was cached indefinitely; in 15 it is not cached at all. After an upgrade, pages that had been static start hitting the API on every request — visible as a traffic spike to the upstream and as slower responses. The audit is mechanical: find every fetch that has no cache/next.revalidate, and decide per call. POST requests are never cached in either version, and fetch in a Route Handler follows the same rules as one in a page.

bash
grep -rn "await fetch(" app/ | grep -v "no-store\|force-cache\|revalidate"

2. revalidate is stale-while-revalidate, not a timer that blocks

text
t=0 page rendered, cached with revalidate: 60 t=61 request arrives -> stale HTML served immediately, revalidation starts t=61+ background render finishes, cache updated t=62 next request sees fresh data

The user at t=61 sees the old page. That is the contract, and it is why a "just updated" value can be one request behind. When a mutation must be visible immediately, do not shorten the window — call revalidateTag from the action, which marks the entry stale and makes the next request wait for a fresh render.

3. Tags: granularity decides how much you invalidate

tsx
// Tag with the entity and the collection await fetch(`https://api.example.com/products/${id}`, { next: { tags: [`product:${id}`, "products"] } });

Invalidating products re-renders every product page; invalidating product:abc re-renders one. Tag names are arbitrary strings, and a common bug is a tag built with a different separator in the writer and the invalidator (product:${id} vs product-${id}), which silently does nothing. Keep the tag builders in one module so both sides use the same function.

4. Dynamic APIs opt a route out of caching entirely

tsx
import { cookies, headers } from "next/headers"; export default async function Page() { const token = (await headers()).get("authorization"); // route is now dynamic const data = await fetch(url, { next: { revalidate: 3600 } }); // still cached return <View data={data} />; }

Using cookies() or headers() makes the route dynamic, but the individual fetch data cache still applies. That combination is useful — cached upstream data personalised at render time — and confusing when a developer assumes one implies the other. To keep the route static and still personalise, read the cookie in a client component or wrap the dynamic part in <Suspense> so the shell can be prerendered.

5. revalidatePath types and what a path invalidates

tsx
revalidatePath("/products"); // that URL revalidatePath("/products/[id]", "page"); // every page under the dynamic segment revalidatePath("/", "layout"); // everything under the root layout

revalidatePath("/products") does not invalidate /products/abc. The second form with "page" is required for a dynamic segment, and "layout" is the blunt instrument that clears all routes under that layout. Since Server Actions cannot know which client-side router cache entries exist, the framework also sends a refresh signal that updates the browser's router cache for the current route — a differing revalidatePath in the action is the usual reason a UI shows stale data after a successful submit.

Common Runtime & Configuration Mistakes

SymptomCauseFix
Data refetched on every request after upgradev15 default no-storeAdd next: { revalidate }
Data never updatesforce-cache with no tagsTag it and invalidate, or use a window
Mutation not visible until reloadOnly the data cache invalidated, not the routerevalidatePath in the same action
revalidateTag does nothingTag string mismatch or no tag on the fetchShare a tag builder module
Page re-renders constantlycookies()/headers() in the treeMove behind Suspense
Build output lists a route as dynamicfetchCache or dynamic configSet the segment config deliberately
Stale prices for a minuterevalidate is stale-while-revalidateInvalidate on write
Cache shared between usersCached fetch that depends on a user tokenInclude the token in the URL or use no-store
unstable_cache returns old values in devDev server caches across HMRRestart the dev server
Route handler always dynamicGET handlers are not cached in 15Opt in explicitly with a window

Caching in the App Router is opt-in and layered: the fetch call, the segment config, and the route's use of dynamic APIs each have a say. Decide per request what staleness is acceptable, tag what you will need to invalidate, and invalidate from the mutation rather than hoping the window is short enough.

Try matching browser tools

All tools

Small utilities that fit Next.js work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Next.js guides

More in Next.js

All Next.js guides

The guides filed next to this one in Next.js, in library order.