1. Introduction 🚀

Caching is one of the most powerful — and most misunderstood — parts of Next.js. Done well, it makes your app feel instant; done poorly, it serves stale data to users who expect fresh content. This tutorial breaks down every caching layer in Next.js, from request-level memoization all the way up to the CDN, and shows you how to invalidate each one intentionally.

2. What is Caching? 🤔

Caching means storing the result of expensive work — a database query, a rendered page, a fetch call — so a future request can reuse it instead of redoing that work from scratch.

3. Why Caching Matters ⚡

Without caching, every request would re-run every data fetch and re-render every component from zero — even if nothing changed since the last request a second ago. Caching trades a small risk of staleness for a large gain in speed and cost.

4. Next.js Caching System 🗂️

Next.js layers four distinct caching mechanisms on top of each other, each operating at a different scope and lifetime.

5. Request Memoization 🧠

Within a single render pass, calling fetch with the same URL and options multiple times only triggers one actual network request — the rest are automatically deduplicated.

async function getUser(id: string) {
  const res = await fetch(`https://api.example.com/users/${id}`);
  return res.json();
}

export default async function Page() {
  // Both calls resolve from the same underlying request
  const userA = await getUser('1');
  const userB = await getUser('1');
  return <div>{userA.name}</div>;
}

6. Data Cache 💾

The Data Cache persists the results of fetch calls across requests and deployments, unless you explicitly opt out. This is what allows a data-fetching page to remain fast without hitting the origin every time.

async function getPosts() {
  const res = await fetch('https://api.example.com/posts', {
    cache: 'force-cache', // default behavior for most fetches
  });
  return res.json();
}

7. Full Route Cache 🖼️

At build time (or after revalidation), Next.js can cache the fully rendered RSC payload and HTML for a route — the Full Route Cache — so subsequent requests skip rendering entirely.

8. Router Cache 🧭

On the client, Next.js keeps an in-memory cache of previously visited route segments, making back/forward navigation and prefetched links feel instant without a server round-trip.

9. Client Cache 🌐

Beyond the Router Cache, standard browser-level HTTP caching still applies to static assets like images, scripts, and fonts, governed by normal Cache-Control response headers.

module.exports = {
  async headers() {
    return [
      {
        source: '/images/:path*',
        headers: [{ key: 'Cache-Control', value: 'public, max-age=31536000, immutable' }],
      },
    ];
  },
};

10. Static Caching 🧊

A route is statically rendered when Next.js can determine its output at build time (or on first request) and reuse it for every subsequent visitor — the fastest possible path.

export default async function BlogPage() {
  const posts = await fetch('https://api.example.com/posts').then((r) => r.json());
  return <PostList posts={posts} />;
}

11. Dynamic Caching 🔄

A route becomes dynamic — rendered fresh on every request — when it reads request-specific data such as cookies, headers, or search params, or when a fetch explicitly opts out of caching.

import { cookies } from 'next/headers';

export default async function Dashboard() {
  const session = cookies().get('session'); // forces dynamic rendering
  return <div>Welcome back!</div>;
}

12. Cache Control 🎛️

You control fetch-level caching with the cache option, and time-based revalidation with next.revalidate.

// Never cache — always fetch fresh
fetch(url, { cache: 'no-store' });

// Cache indefinitely until manually revalidated
fetch(url, { cache: 'force-cache' });

// Cache, but revalidate after 60 seconds
fetch(url, { next: { revalidate: 60 } });

13. Cache Tags 🏷️

Tags let you label a cached fetch entry so it can be invalidated by name later, rather than by path — useful when one piece of data appears on multiple pages.

async function getProduct(id: string) {
  const res = await fetch(`https://api.example.com/products/${id}`, {
    next: { tags: ['product', `product-${id}`] },
  });
  return res.json();
}

14. cache()

The cache() function from React memoizes the return value of an arbitrary function for the duration of a single render — useful for deduping non-fetch work like database calls.

import { cache } from 'react';

export const getUser = cache(async (id: string) => {
  return db.user.findUnique({ where: { id } });
});

15. unstable_cache

unstable_cache extends caching to non-fetch data sources — like direct database queries — giving them the same tag- and time-based revalidation as the Data Cache.

import { unstable_cache } from 'next/cache';

export const getCachedPosts = unstable_cache(
  async () => db.post.findMany(),
  ['posts-list'],
  { tags: ['posts'], revalidate: 3600 }
);

16. revalidate ⏱️

The revalidate option — whether on a fetch call, a route segment config export, or unstable_cache — defines how long, in seconds, a cache entry stays fresh before Next.js fetches new data.

export const revalidate = 3600; // revalidate this route every hour

17. Time-Based Revalidation ⏳

This is Incremental Static Regeneration in practice: a cached page keeps serving instantly, and Next.js regenerates it in the background once the revalidate window has passed.

18. On-Demand Revalidation 🔔

Rather than waiting for a timer, you can trigger revalidation immediately — typically from a webhook fired when content changes in a CMS.

import { revalidateTag } from 'next/cache';

export async function POST(request: Request) {
  const { tag } = await request.json();
  revalidateTag(tag);
  return Response.json({ revalidated: true });
}

19. revalidatePath

revalidatePath clears the Full Route Cache and Data Cache for a specific path, forcing the next visit to that route to render fresh.

'use server';
import { revalidatePath } from 'next/cache';

export async function publishPost(id: string) {
  await db.post.update({ where: { id }, data: { published: true } });
  revalidatePath('/blog');
}

20. revalidateTag

revalidateTag invalidates every cached fetch entry sharing a given tag, regardless of which route it was fetched from — more precise than invalidating an entire path.

'use server';
import { revalidateTag } from 'next/cache';

export async function updateProduct(id: string) {
  await db.product.update({ where: { id }, data: { inStock: false } });
  revalidateTag(`product-${id}`);
}

21. updateTag

updateTag is a newer, more surgical revalidation primitive: instead of clearing an entire tag's cache, it lets you update the cached value in place immediately after a mutation, avoiding a stale read on the very next request.

'use server';
import { updateTag } from 'next/cache';

export async function toggleLike(postId: string) {
  await db.post.update({ where: { id: postId }, data: { likes: { increment: 1 } } });
  updateTag(`post-${postId}`);
}

22. Cache Invalidation 🧹

There's a well-known saying in computer science:

23. Dynamic Rendering Triggers 🔥

Certain APIs automatically force a route out of static rendering and into dynamic, per-request rendering. Knowing these prevents accidentally losing the Full Route Cache.

24. Fetch Cache Options 🔧

25. Database Caching 🗄️

For direct database access (no fetch involved), wrap your query functions with unstable_cache or React's cache() to get equivalent caching and tag-based invalidation.

import { unstable_cache } from 'next/cache';

export const getActiveUsers = unstable_cache(
  () => db.user.findMany({ where: { active: true } }),
  ['active-users'],
  { tags: ['users'], revalidate: 300 }
);

26. CDN Caching 🌍

When deployed behind a CDN, statically rendered pages and cached responses can also be cached at the edge, serving requests without ever reaching your origin server.

27. Browser Caching 🖥️

Static assets served from public/ and build output are typically sent with long-lived, immutable Cache-Control headers, since their filenames are content-hashed and change whenever the content does.

module.exports = {
  async headers() {
    return [
      { source: '/_next/static/:path*', headers: [{ key: 'Cache-Control', value: 'public, max-age=31536000, immutable' }] },
    ];
  },
};

28. Performance Optimization 🏎️

29. Debugging Cache Issues 🐞

30. Best Practices ✅

31. Common Mistakes 🚫

32. Frequently Asked Questions ❓

33. Summary 📚