Caching and Revalidation: The 4 Levels of Next.js Caching

Why This Matters#

In high-throughput web applications, database latency and external microservice responsiveness directly dictate TTFB and end-user perception. Uncontrolled redundant SQL queries and outbound HTTP requests deplete compute resources and quickly exhaust database connection pools.

The Next.js App Router incorporates a multi-tiered caching architecture harmonizing React core primitives with the Next.js runtime. This system spans the entire data lifecycle — from single-render CPU memory deduplication to distributed edge CDN caching of static artifacts and client-side route segment caching inside the user's browser.

A rigorous mental model of each caching layer, its de-optimization boundaries, and on-demand invalidation mechanisms distinguishes an engineer battling stale production state from an architect designing resilient, high-speed distributed systems.

Mental Model#

Next.js operates 4 independent caching layers, each serving a targeted purpose with isolated scopes and distinct lifecycles:

1. Request Memoization (React): An in-memory cache on the server scoped to a single request lifecycle. Prevents duplicate network requests across isolated Server Components within the same render tree.
2. Data Cache (Next.js): Persistent server-side storage (filesystem, Redis, or cloud KV) retaining HTTP response bodies and expensive computations across distinct user sessions.
3. Full Route Cache (Next.js): The server cache for pre-compiled HTML documents and binary React Server Component Flight Payloads corresponding to static routes.
4. Client Router Cache (Next.js / Browser): An in-memory cache of UI route segments within the client browser session, powering instantaneous client-side transitions (Soft Navigation) without server round-trips.

Explore the cache flow simulator below to observe how requests navigate across all 4 caching layers:

Syntax and API#

1. Request Memoization (React)#

React automatically deduplicates fetch invocations sharing identical URLs and options across the server component render tree. The lifetime of this cache matches the millisecond duration of server response construction.

[!IMPORTANT] Request Memoization is never shared across distinct users or requests. It is strictly an intra-request optimization scoped to one React Server Components render pass. There is no global switch to disable it, but it can be bypassed per call by supplying an explicit AbortController (via the signal property) to fetch.

// app/components/Header.tsx
export async function Header() {
  // Dispatches physical network call
  const user = await fetch('https://api.internal/user/me').then(r => r.json());
  return <header>User: {user.name}</header>;
}

// app/components/Sidebar.tsx
export async function Sidebar() {
  // Instantly retrieved from Request Memoization (RAM) without repeating HTTP call
  const user = await fetch('https://api.internal/user/me').then(r => r.json());
  return <aside>Role: {user.role}</aside>;
}

2. Data Cache Management#

In Next.js 15+, the standard fetch is un-cached by default (cache: 'no-store'). Caching at the Data Cache layer requires explicit configuration.

// 1. Next.js 15+ default: no-store (always fetches fresh data from upstream)
const freshData = await fetch('https://api.internal/rates');

// 2. Persistent caching (retained indefinitely until explicitly revalidated)
const immutableData = await fetch('https://api.internal/dictionary', {
  cache: 'force-cache',
});

// 3. Time-based revalidation (Stale-While-Revalidate for 60 seconds)
const catalog = await fetch('https://api.internal/products', {
  next: { revalidate: 60 },
});

// 4. Cache tagging for precise on-demand invalidation
const profile = await fetch('https://api.internal/user/10', {
  next: { tags: ['user-10', 'users'] },
});

3. On-Demand Revalidation: revalidateTag and revalidatePath#

To purge outdated entries upon state-changing events (Server Actions, Webhooks), import invalidation utilities from next/cache. These functions invalidate entries in the Data Cache as well as affected branches in the Full Route Cache.

'use server';

import { revalidatePath, revalidateTag } from 'next/cache';
import { db } from '@/lib/db';
import { products } from '@/lib/schema';
import { eq } from 'drizzle-orm';

export async function updateProductPrice(productId: string, newPrice: number): Promise<{ success: boolean }> {
  // 1. Mutate record in primary database
  await db.update(products).set({ price: newPrice }).where(eq(products.id, productId));

  // 2. Targeted tag invalidation (affects every query sharing this tag across the application)
  revalidateTag(`product-${productId}`);
  revalidateTag('catalog-list');

  // 3. Invalidate specific route path
  revalidatePath(`/products/${productId}`, 'page');

  return { success: true };
}

Practical Patterns#

Pattern 1: Stale-While-Revalidate (SWR) Under the Hood#

When setting next: { revalidate: 60 }, the system follows a defined lifecycle protocol:

1. Request at T = 0s (Cold Start): Cache miss. The server queries upstream, returns data to the client, and commits the response to Data Cache with an associated timestamp.
2. Requests at T = 1..59s (Cache Hit): All incoming requests receive the cached result from the Data Cache with sub-millisecond response times.
3. Request at T = 60s+ (Stale Window): Data is marked stale. Next.js immediately serves the stale data (preserving low TTFB), while scheduling an asynchronous background worker to re-fetch upstream data.
4. Requests at T = 62s+ (Cache Replaced): Following successful completion of the background worker, the Data Cache entry is updated, and subsequent visitors receive the updated dataset.

Pattern 2: Caching ORM and SQL Queries with unstable_cache and 'use cache'#

Direct database queries (Prisma, Drizzle, pg) do not use global fetch and bypass the Data Cache by default. To persist their output, wrap them in unstable_cache, or employ the 'use cache' directive (Next.js 15.1+ with the dynamicIO flag).

import 'server-only';
import { unstable_cache } from 'next/cache';
import { db } from '@/lib/db';
import { projects } from '@/lib/schema';
import { eq } from 'drizzle-orm';

export interface ProjectDTO {
  id: string;
  name: string;
  stars: number;
}

export const getCachedProject = (projectId: string) => {
  return unstable_cache(
    async (id: string): Promise<ProjectDTO | null> => {
      const record = await db.query.projects.findFirst({
        where: eq(projects.id, id),
      });
      return record ?? null;
    },
    ['project-detail-key', projectId], // Cache key parts
    {
      revalidate: 3600, // 1 hour
      tags: [`project-${projectId}`, 'projects'],
    }
  )(projectId);
};

Pattern 3: Opting Out of the Full Route Cache#

A route automatically transitions from static compilation (Static Generation) to dynamic execution (Dynamic Rendering per request) when dynamic request functions are accessed:

import { cookies, headers } from 'next/headers';

// Explicitly opt out of Full Route Cache for the entire segment
export const dynamic = 'force-dynamic';

export default async function AnalyticsPage() {
  // Asynchronous headers and cookies access in Next.js 15+ marks the route as dynamic
  const headersList = await headers();
  const userAgent = headersList.get('user-agent') ?? 'unknown';

  const cookieStore = await cookies();
  const sessionId = cookieStore.get('sid')?.value;

  return (
    <main className="p-6">
      <h1>System Analytics</h1>
      <p>Client: {userAgent}</p>
      <p>Session ID: {sessionId}</p>
    </main>
  );
}

Common Pitfalls#

// ❌ ERROR: Attempting to read cookies inside a cached callback
const getAuthData = unstable_cache(
  async () => {
    const cookieStore = await cookies(); // Throws DynamicServerError!
    return fetchUserData(cookieStore.get('token')?.value);
  },
  ['auth-user-key']
);

// ✅ CORRECT: Pass dynamic variables as explicit parameters included in key parts
const getAuthData = (token: string) => 
  unstable_cache(
    async (authToken: string) => fetchUserData(authToken),
    ['auth-user-key', token]
  )(token);

// ❌ Error: Cache key is static, causing all users to receive user data for the first queried ID
const getUser = unstable_cache(
  async (id: string) => db.query.users.findFirst(eq(users.id, id)),
  ['user'] 
);

// ✅ Correct: The entity ID is incorporated into the cache key parts
const getUser = unstable_cache(
  async (id: string) => db.query.users.findFirst(eq(users.id, id)),
  ['user', id]
);

Comparative Matrix of the 4 Caching Layers#

Interview Questions#