Next.js Caching

Quick Reference

Next.js 16: 'use cache' Directive

Fetch Options

When to Use This Skill

Use for caching and revalidation:

• Understanding Next.js caching behavior
• Configuring fetch caching strategies
• Setting up Incremental Static Regeneration (ISR)
• Implementing on-demand revalidation
• Debugging cache issues

Related skills:

• For data fetching: see nextjs-data-fetching
• For Server Actions: see nextjs-server-actions
• For static generation: see nextjs-deployment

---

Next.js Caching

Caching Overview

Next.js has four caching mechanisms:

Request Memoization

Automatic Deduplication

// This is automatically memoized - only one fetch happens
async function getUser(id: string) {
  const res = await fetch(`https://api.example.com/​users/​${id}`);
  return res.json();
}

// Layout uses getUser
export default async function Layout({ children }: { children: React.ReactNode }) {
  const user = await getUser('1'); // First call - fetches
  return <div>{children}</​div>;
}

// Page also uses getUser
export default async function Page() {
  const user = await getUser('1'); // Second call - uses cached result
  return <div>{user.name}</​div>;
}

Manual Memoization with cache()

import { cache } from 'react';

// For non-fetch functions like database queries
export const getUser = cache(async (id: string) => {
  return db.users.findUnique({ where: { id } });
});

// Both will use the same cached result
const user1 = await getUser('1');
const user2 = await getUser('1');

Data Cache

Caching with fetch()

// Cached indefinitely (default)
const data = await fetch('https://api.example.com/​data');

// Opt out of caching
const data = await fetch('https://api.example.com/​data', {
  cache: 'no-store',
});

// Time-based revalidation
const data = await fetch('https://api.example.com/​data', {
  next: { revalidate: 3600 }, // Revalidate every hour
});

// Tag-based caching
const data = await fetch('https://api.example.com/​posts', {
  next: { tags: ['posts'] },
});

unstable_cache for Non-Fetch

import { unstable_cache } from 'next/​cache';

const getCachedUser = unstable_cache(
  async (userId: string) => {
    return db.users.findUnique({ where: { id: userId } });
  },
  ['user'], // Cache key parts
  {
    revalidate: 3600, // 1 hour
    tags: ['users'],
  }
);

export default async function UserPage({ params }: { params: { id: string } }) {
  const user = await getCachedUser(params.id);
  return <div>{user?.name}</​div>;
}

Route Segment Config

// Opt entire route out of caching
export const dynamic = 'force-dynamic';

// Set revalidation for entire route
export const revalidate = 60; // seconds

// Disable cache for all fetches in route
export const fetchCache = 'force-no-store';

// Force static generation
export const dynamic = 'force-static';

Revalidation

Time-Based Revalidation

// Fetch with revalidation
const data = await fetch('https://api.example.com/​data', {
  next: { revalidate: 60 }, // Revalidate after 60 seconds
});

// Route-level revalidation
export const revalidate = 60;

On-Demand Revalidation

// app/​actions.ts
'use server';

import { revalidatePath, revalidateTag } from 'next/​cache';

// Revalidate a specific path
export async function updatePost(id: string, data: FormData) {
  await db.posts.update({ where: { id }, data: { /​* ... */ } });

  // Revalidate the specific post page
  revalidatePath(`/​posts/​${id}`);

  // Revalidate the posts list
  revalidatePath('/​posts');
}

// Revalidate by tag
export async function createPost(data: FormData) {
  await db.posts.create({ data: { /​* ... */ } });

  // All fetches with 'posts' tag will be revalidated
  revalidateTag('posts');
}

Revalidation API Route

// app/​api/​revalidate/​route.ts
import { revalidatePath, revalidateTag } from 'next/​cache';
import { NextRequest, NextResponse } from 'next/​server';

export async function POST(request: NextRequest) {
  const secret = request.headers.get('x-revalidate-secret');

  if (secret !== process.env.REVALIDATION_SECRET) {
    return NextResponse.json({ error: 'Invalid secret' }, { status: 401 });
  }

  const body = await request.json();

  if (body.tag) {
    revalidateTag(body.tag);
  }

  if (body.path) {
    revalidatePath(body.path);
  }

  return NextResponse.json({ revalidated: true, now: Date.now() });
}

Tag-Based Caching

// Fetch with tags
async function getPosts() {
  const res = await fetch('https://api.example.com/​posts', {
    next: { tags: ['posts', 'content'] },
  });
  return res.json();
}

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

// Revalidate all posts
revalidateTag('posts');

// Revalidate specific post
revalidateTag('post-123');

// Revalidate all content
revalidateTag('content');

Full Route Cache

Static Routes

// Automatically cached at build time
export default async function StaticPage() {
  const data = await getData();
  return <div>{data}</​div>;
}

// Force static
export const dynamic = 'force-static';

Dynamic Routes with generateStaticParams

// app/​posts/[slug]/​page.tsx
export async function generateStaticParams() {
  const posts = await db.posts.findMany({ select: { slug: true } });
  return posts.map((post) => ({ slug: post.slug }));
}

// Pages are pre-rendered at build time
export default async function PostPage({ params }: { params: { slug: string } }) {
  const post = await getPost(params.slug);
  return <article>{post.content}</​article>;
}

Opting Out

// Dynamic route - not cached
export const dynamic = 'force-dynamic';

// Or use dynamic functions
import { headers, cookies } from 'next/​headers';

export default async function Page() {
  const headersList = await headers(); // Makes route dynamic
  return <div>...</​div>;
}

Router Cache (Client-Side)

Prefetching

import Link from 'next/​link';

// Prefetch on hover (default)
<Link href="/​about">About</​Link>

// Disable prefetching
<Link href="/​dashboard" prefetch={false}>Dashboard</​Link>

Invalidating Router Cache

'use client';

import { useRouter } from 'next/​navigation';

export function RefreshButton() {
  const router = useRouter();

  const handleRefresh = () => {
    // Refresh current route and invalidate cache
    router.refresh();
  };

  return <button onClick={handleRefresh}>Refresh</​button>;
}

revalidatePath and Router Cache

// Server Action
'use server';

import { revalidatePath } from 'next/​cache';

export async function updateData() {
  // Update data in database
  await db.data.update({ /​* ... */ });

  // This also clears the Router Cache for this path
  revalidatePath('/​data');
}

Cache Headers

Route Handler Caching

// app/​api/​data/​route.ts
import { NextResponse } from 'next/​server';

export async function GET() {
  const data = await fetchData();

  return NextResponse.json(data, {
    headers: {
      'Cache-Control': 'public, s-maxage=3600, stale-while-revalidate=86400',
    },
  });
}

generateStaticParams with Dynamic

// Generate some pages statically, allow others dynamically
export async function generateStaticParams() {
  // Only pre-render the top 100 posts
  const posts = await db.posts.findMany({ take: 100 });
  return posts.map((post) => ({ slug: post.slug }));
}

// Allow dynamic rendering for posts not in generateStaticParams
export const dynamicParams = true; // default

// Or 404 for unknown slugs
export const dynamicParams = false;

Caching Strategies

Stale-While-Revalidate Pattern

// Serve cached content while revalidating in background
const data = await fetch('https://api.example.com/​data', {
  next: { revalidate: 60 },
});

// First request after 60s: serves stale, triggers revalidation
// Subsequent requests: serve fresh data

Cache-First Strategy

// Cache indefinitely, revalidate on-demand
const data = await fetch('https://api.example.com/​static-data');
// Use revalidateTag('static-data') when data changes

Network-First Strategy

// Always fetch fresh data
const data = await fetch('https://api.example.com/​realtime', {
  cache: 'no-store',
});

Debugging Cache

Cache Status Headers

// Enable cache debugging
// next.config.js
module.exports = {
  logging: {
    fetches: {
      fullUrl: true,
    },
  },
};

Check Cache Hit/​Miss

// In development, check terminal for cache status
// HIT - served from cache
// MISS - fetched from origin
// STALE - served stale, revalidating

Best Practices