Caching Architecture

Priority: P1 (HIGH)

Next.js has 4 distinct caching layers. Understanding them prevents stale data bugs.

Implementation Guidelines

• Next.js 15+ Standard: Use

  fetch

  with

  revalidate: number

  or

  cache: 'force-cache'

  for API calls. Use

  unstable_cache

  or the new

  'use cache'

  (experimental) for custom data stores.
• Layers: Distinguish between Data Cache (persistent across requests) and Request Memoization (React's lifecycle specific). Use

  cache()

  from React to deduplicate fetches within a single render.
• Invalidation: Use

  revalidatePath('/')

  after mutations or

  revalidateTag('tag-name')

  for granular cache purging.
• Client Cache: Understand the Router Cache (in-memory on client) and its 30s-min lifespan. Clear it using

  router.refresh()

  .
• Static Assets: Leverage

  generateStaticParams

  for pre-rendering static routes at build time. Use ISR (Incremental Static Regeneration) for content that updates periodically.
• Streaming: Combine

  Suspense

  with

  fetch

  triggers to prevent slow data from blocking the entire page render.
• Next.js 16+: Favor

  'use cache'

  and

  cacheLife()

  over

  revalidate: number

  where available for deterministic caching.

cache()

'use cache'

revalidateTag

router.refresh()

Implementation Details

See Cache Components & PPR for detailed key generation, closure constraints, and invalidation strategies.

Anti-Patterns

• No

  unstable_cache

  in Next.js 16+: Use

  'use cache'

  directive with

  cacheLife()

  instead.
• No

  router.refresh()

  for server data: Prefer

  revalidateTag()

  for targeted cache busting.
• No caching user-specific data at route level: Wrap personal data in

  <Suspense>

  with

  'use cache'

  .
• No long-lived cache without tags: Assign

  cacheTag()

  for fine-grained invalidation control.