Next.js Caching Deep Dive — Understand and control the four caching layers

// Layer 1: Request Memoization — automatic dedup within a single render
// Both components call the same function, but only ONE database query executes
async function getUser(id: string) {
  // React deduplicates this automatically during a single render pass
  return db.user.findUnique({ where: { id } });
}
 
// Layer 2: Data Cache — persistent cache for fetch() results
const data = await fetch("https://api.example.com/products", {
  next: { revalidate: 3600, tags: ["products"] },
});
 
// Layer 3: Full Route Cache — pre-rendered HTML for static routes
// Automatic for pages without dynamic functions (cookies, headers, searchParams)
 
// Layer 4: Router Cache — client-side cache for visited routes
// Automatic for all navigations, cached for 30s (dynamic) or 5min (static)
 
// Invalidation
import { revalidateTag, revalidatePath } from "next/cache";
 
// Targeted: invalidate all fetches tagged "products"
revalidateTag("products");
 
// Broad: invalidate a specific route
revalidatePath("/products");

// ---- BEFORE: No caching strategy — every page load hits the database ----
 
// app/products/page.tsx
export const dynamic = "force-dynamic"; // Opts out of ALL caching
 
export default async function ProductsPage() {
  // Hits database on EVERY request — 120ms per visit
  const products = await db.product.findMany({
    include: { category: true },
    orderBy: { createdAt: "desc" },
  });
 
  // Same query executed AGAIN for the count
  const allProducts = await db.product.findMany();
  const totalCount = allProducts.length;
 
  return (
    <div>
      <h1>Products ({totalCount})</h1>
      {products.map((p) => (
        <ProductCard key={p.id} product={p} />
      ))}
    </div>
  );
}
 
// app/products/[id]/page.tsx
export const dynamic = "force-dynamic";
 
export default async function ProductPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  // Hits database on every visit — even for the same product
  const product = await db.product.findUnique({
    where: { id },
    include: { reviews: true, seller: true },
  });
 
  return <ProductDetail product={product} />;
}
 
// Result: 120ms per page load, no caching, database under constant load
 
// ---- AFTER: Layered caching strategy — sub-50ms for cached pages ----
 
// lib/data/products.ts — Centralized data access with caching
import { cache } from "react";
import { unstable_cache } from "next/cache";
 
// Layer 1: Request Memoization — dedup within a single render
// React's cache() ensures this only runs once per render pass,
// even if called from multiple Server Components
export const getProductById = cache(async (id: string) => {
  return db.product.findUnique({
    where: { id },
    include: { reviews: true, seller: true },
  });
});
 
// Layer 2: Data Cache — persistent cache across requests
export const getProducts = unstable_cache(
  async () => {
    return db.product.findMany({
      include: { category: true },
      orderBy: { createdAt: "desc" },
    });
  },
  ["products-list"],          // Cache key
  {
    revalidate: 3600,          // Revalidate every hour
    tags: ["products"],        // Tag for targeted invalidation
  }
);
 
export const getProductCount = unstable_cache(
  async () => {
    return db.product.count();
  },
  ["product-count"],
  {
    revalidate: 3600,
    tags: ["products"],
  }
);
 
// app/products/page.tsx — Uses cached data
export default async function ProductsPage() {
  // Both use the "products" cache — fast after first request
  const [products, totalCount] = await Promise.all([
    getProducts(),
    getProductCount(),
  ]);
 
  return (
    <div>
      <h1>Products ({totalCount})</h1>
      {products.map((p) => (
        <ProductCard key={p.id} product={p} />
      ))}
    </div>
  );
}
 
// Layer 3: Full Route Cache — pre-render product pages at build time
export async function generateStaticParams() {
  const products = await db.product.findMany({ select: { id: true } });
  return products.map((p) => ({ id: p.id }));
}
 
// app/products/[id]/page.tsx — Statically generated + ISR
export const revalidate = 3600; // ISR: regenerate every hour
 
export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const product = await getProductById(id);
 
  if (!product) notFound();
 
  return <ProductDetail product={product} />;
}
 
// Invalidation: Server Action after product update
// app/actions/products.ts
"use server";
 
import { revalidateTag, revalidatePath } from "next/cache";
 
export async function updateProduct(id: string, data: ProductUpdateData) {
  await db.product.update({ where: { id }, data });
 
  // Invalidate the data cache for all product fetches
  revalidateTag("products");
 
  // Invalidate the specific product page route cache
  revalidatePath(`/products/${id}`);
}
 
export async function deleteProduct(id: string) {
  await db.product.delete({ where: { id } });
 
  // Invalidate everything tagged "products"
  revalidateTag("products");
 
  // Invalidate the product listing page
  revalidatePath("/products");
}

// No caching — always fresh data
const data = await fetch("https://api.example.com/live-prices", {
  cache: "no-store",
});
 
// Equivalent: dynamic route segment config
export const dynamic = "force-dynamic";
export const revalidate = 0;

// Page-level revalidation
export const revalidate = 60; // Revalidate every 60 seconds
 
// Fetch-level revalidation
const data = await fetch(url, {
  next: { revalidate: 300 }, // This specific fetch caches for 5 minutes
});

"use server";
 
import { revalidateTag, revalidatePath } from "next/cache";
 
export async function publishPost(id: string) {
  await db.post.update({
    where: { id },
    data: { published: true },
  });
 
  // Granular: only invalidate blog-related caches
  revalidateTag("blog-posts");
  revalidateTag(`post-${id}`);
 
  // Broad: invalidate the entire blog section
  revalidatePath("/blog", "layout");
}

// next.config.ts — expose cache status headers
const nextConfig = {
  logging: {
    fetches: {
      fullUrl: true, // Log full fetch URLs with cache status
    },
  },
};
 
// Check response headers in DevTools:
// x-nextjs-cache: HIT    — served from Full Route Cache
// x-nextjs-cache: MISS   — rendered on demand, now cached
// x-nextjs-cache: STALE  — served stale, revalidating in background