Next.js Caching Strategies

Control Next.js's four cache layers to balance freshness, performance, and cost

When to Use

• Deciding how long fetched data should remain valid before re-fetching
• Implementing on-demand cache invalidation triggered by CMS or database mutations
• Debugging stale data that persists despite server restarts or code changes
• Optimizing expensive API calls with appropriate cache lifetimes
• Understanding why a page is not updating after deploying new data

Instructions

1. Use

   fetch(url, { next: { revalidate: 60 } })

   to cache a fetch result for 60 seconds (ISR-style).
2. Use

   fetch(url, { cache: 'no-store' })

   to opt out of caching entirely — equivalent to always fetching fresh data.
3. Use

   fetch(url, { next: { tags: ['posts'] } })

   to attach a cache tag — call

   revalidateTag('posts')

   later to purge it.
4. Use

   unstable_cache(fn, keyParts, { tags, revalidate })

   to cache non-fetch data (database queries, third-party SDK calls).
5. Set

   export const revalidate = 60

   at the page or layout level as a per-segment default that applies to all fetches in that segment.
6. Set

   export const dynamic = 'force-dynamic'

   to opt the entire route out of all caching — equivalent to SSR.
7. Call

   revalidatePath('/posts')

   from a Server Action or Route Handler to purge all cache entries for that path.
8. Use

   revalidateTag('tag')

   for targeted invalidation without knowing specific paths — one tag can cover many routes.

// lib/posts.ts — cached database query with tags
import { unstable_cache } from 'next/cache';
import { db } from '@/lib/db';

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

// app/api/revalidate/route.ts — webhook-triggered on-demand revalidation
import { 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.REVALIDATE_SECRET) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }
  const { tag } = await request.json();
  revalidateTag(tag);
  return NextResponse.json({ revalidated: true });
}

Details

Next.js App Router has four distinct caches that interact:

1. Request Memoization — deduplicates identical

   fetch()

   calls within a single request lifecycle. Automatic, not configurable. Reset per request.
2. Data Cache — persists

   fetch()

   results across requests and deployments. Controlled by

   revalidate

   and

   cache

   fetch options. The primary cache for server-side data.
3. Full Route Cache — caches the rendered HTML and RSC payload of static routes. Populated at build time and on background revalidation. Invalidated by

   revalidatePath()

   .
4. Router Cache — client-side cache of RSC payloads for previously visited routes. Reduces server requests during navigation. Automatically expires; call

   router.refresh()

   to purge.

unstable_cache

vs fetch cache:

fetch()

caching only applies to the native

fetch

function. Use

unstable_cache

to cache ORM queries (Prisma, Drizzle), Redis calls, or any async function. The API is identical in semantics — tags, revalidate, key parts.

Opt-out cascade: Using

cookies()

,

headers()

, or

searchParams

in a Server Component automatically opts that route into dynamic rendering, bypassing the Full Route Cache. A single dynamic function in a layout propagates dynamism to all child routes.

Debugging stale cache: Run

next build

and inspect the build output — routes marked

○

are static,

λ

are dynamic,

ƒ

are ISR. Use

NEXT_PRIVATE_DEBUG_CACHE=1

environment variable in development to log cache hits and misses.

Source

https://nextjs.org/docs/app/building-your-application/caching

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.