next-cache-components_skill

Overview

This skill documents Next.js 16 Cache Components for Partial Prerendering (PPR), covering the 'use cache' directive, cacheLife profiles, cacheTag/updateTag APIs, and migration from unstable_cache. It explains how to mix static, cached, and dynamic content in one route, configure cache lifetimes and tags, and handle cache invalidation patterns. The content focuses on practical usage, constraints, and common migration steps.

How this skill works

Cache Components let you mark server components or functions with 'use cache' so their async results are stored and reused according to configured lifetimes or built-in profiles. cacheLife controls stale/revalidate/expire behavior, cacheTag attaches semantic tags for selective invalidation, updateTag forces immediate cache refresh within the same request, and revalidateTag triggers background revalidation. Dynamic pieces remain runtime-only and are streamed with Suspense; runtime APIs like cookies() cannot be used inside normal cached functions unless using 'use cache: private'.

When to use it

• When you need fast, reusable server-rendered fragments alongside dynamic streaming content.
• To reduce backend load for data that can tolerate stale responses and background revalidation.
• When you want fine-grained invalidation using tags for specific resources (products, posts, etc.).
• During migration from unstable_cache to the Next.js 16 cache directive model.
• When you must combine static layout, cached data, and fresh per-request pieces in a single page.

Best practices

• Enable cacheComponents in next.config.ts instead of experimental flags.
• Prefer descriptive cacheTag values (e.g., 'products', 'product-{id}') to allow targeted invalidation.
• Use built-in cacheLife profiles for common cases; use inline cacheLife({ stale, revalidate, expire }) for precise control.
• Extract runtime-only values (cookies, headers, searchParams) outside cached functions and pass them as arguments so they become part of the cache key.
• Use updateTag() for immediate same-request freshness and revalidateTag() for background refresh after writes.

Example use cases

• Dashboard stats cached hourly with cacheTag('dashboard-stats') while notifications stream in via Suspense.
• A product list cached with cacheLife('hours') and tag 'products', with updateTag('product-123') on edits.
• User profile data cached per-user ID by passing sessionId into a 'use cache' component so session becomes part of the key.
• Migrate unstable_cache patterns to 'use cache' by replacing manual keys with function args and cacheTag/cacheLife calls.