Caching Architecture

Priority: P1 (HIGH)

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

Modern Standard: Cache Components (Next.js 16+)

[!IMPORTANT] Next.js 16 favors the 'use cache' directive over unstable_cache. Wrap dynamic runtime data in <Suspense>.

Core Protocol

1. Dynamic Shell: Keep layouts static or cached; use <Suspense> for user-specific data.
2. Deterministic Cache: Add 'use cache' and cacheLife() to server functions.
3. Invalidation:
   • updateTag(): Immediate sync reflect.
   • revalidateTag(): Background refresh (SWR).

The 4 Caching Layers

| Layer | Where | Control | | :---------------------- | :----- | :----------------------------- | | Request Memoization | Server | React cache() | | Data Cache | Server | 'use cache', revalidateTag | | Full Route Cache | Server | Static Prerendering | | Router Cache | Client | router.refresh() |

Implementation Details

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