nextjs-caching

Quick Reference

Cache Layer	Location	Duration	Purpose
Request Memoization	Server	Per-request	Dedupe same fetches
Data Cache	Server	Persistent	Store fetch results
Full Route Cache	Server	Persistent	Pre-rendered HTML/RSC
Router Cache	Client	Session	Client-side navigation

Next.js 16: 'use cache' Directive

Directive	Scope	Use Case
'use cache'	Default cache	General caching
'use cache: remote'	CDN/Edge cache	Static shared content
'use cache: private'	Per-user cache	User-specific data

Cache Function	Code	Purpose
cacheLife('hours')	Duration	Set cache lifetime
cacheTag('posts')	Tagging	Enable targeted revalidation

Fetch Options

Fetch Option	Code	Effect
Default	fetch(url)	Cached indefinitely
No cache	{ cache: 'no-store' }	Always fresh
Revalidate	{ next: { revalidate: 60 } }	Stale after 60s
Tags	{ next: { tags: ['posts'] } }	Tag for invalidation

Revalidation	Code	Use Case
revalidatePath('/posts')	Path	After mutation
revalidateTag('posts')	Tag	Invalidate tagged data
router.refresh()	Client	Refresh current route

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:

Mechanism	What	Where	Purpose	Duration
Request Memoization	Return values of functions	Server	Avoid duplicate requests in component tree	Per-request
Data Cache	Data	Server	Store data across requests and deployments	Persistent
Full Route Cache	HTML and RSC payload	Server	Reduce rendering cost	Persistent
Router Cache	RSC payload	Client	Reduce server requests on navigation	Session

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

Practice	Description
Use tags for related data	Group related fetches with tags
Revalidate minimally	Only revalidate what changed
Prefer static generation	Use generateStaticParams when possible
Cache database queries	Use unstable_cache for non-fetch
Set appropriate TTL	Balance freshness vs performance
Use ISR for content	Time-based revalidation for content sites