majiayu000 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 overunstable_cache. Wrap dynamic runtime data in<Suspense>.
Core Protocol
- Dynamic Shell: Keep layouts static or cached; use
<Suspense>for user-specific data. - Deterministic Cache: Add
'use cache'andcacheLife()to server functions. - 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.