Nextjs Caching

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.

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.