Expert guidance for Next.js Cache Components and Partial Prerendering (PPR). Use when implementing 'use cache' directive, configuring cache lifetimes with cacheLife(), tagging cached data with cacheTag(), invalidating caches with updateTag()/revalidateTag(), optimizing static vs dynamic content boundaries, managing 'use cache: private' for compliance scenarios, pass-through/interleaving patterns, GET Route Handler caching, debugging cache issues, and reviewing Cache Component implementations.
Expert guidance for Next.js Cache Components and Partial Prerendering (PPR). Use when implementing 'use cache' directive, configuring cache lifetimes with cacheLife(), tagging cached data with cacheTag(), invalidating caches with updateTag()/revalidateTag(), optimizing static vs dynamic content boundaries, managing 'use cache: private' for compliance scenarios, pass-through/interleaving patterns, GET Route Handler caching, debugging cache issues, and reviewing Cache Component implementations.
argument-hint
[pattern or question]
metadata
{"version":"1.0"}
Next.js Cache Components
Auto-activation: Activate this skill automatically in Next.js projects that have
cacheComponents: true in next.config.ts/next.config.js. When detected, apply Cache
Components patterns to all Server Component authoring, data fetching, and caching decisions.
Project Detection
When starting work in a Next.js project, check if Cache Components are enabled:
# Check next.config.ts or next.config.js for cacheComponents
grep -r "cacheComponents" next.config.* 2>/dev/null
If cacheComponents: true is found, apply this skill's patterns proactively when:
Writing React Server Components
Implementing data fetching
Creating Server Actions with mutations
Optimizing page performance
Reviewing existing component code
Cache Components enable Partial Prerendering (PPR) - mixing static HTML shells with dynamic streaming content for optimal performance. Cache Components also enable state preservation during navigation with React's <Activity> component, which can keep cached component trees mounted but hidden.
Philosophy: Code Over Configuration
Cache Components represents a shift from segment configuration to compositional code:
Before (Deprecated)
After (Cache Components)
export const revalidate = 3600
cacheLife('hours') inside 'use cache'
export const dynamic = 'force-static'
Use 'use cache' and Suspense boundaries
All-or-nothing static/dynamic
Granular: static shell + cached + dynamic
Key Principle: Components co-locate their caching, not just their data. Next.js provides build-time feedback to guide you toward optimal patterns.
When writing a React Server Component, walk through these steps in order:
Does the component fetch data or perform I/O?
No → pure component, nothing to decide.
Yes → continue.
Does it depend on request context (cookies(), headers(), searchParams)?
No → continue to step 3.
Yes → continue to step 4.
(No request context) Is the data the same across users?
Yes → add 'use cache' with cacheTag() and cacheLife().
No → wrap rendering in <Suspense> so the dynamic part streams at request time.
(Has request context) Can you extract the runtime data as function arguments?
Yes → read cookies()/headers() outside the cached scope, pass values
into a 'use cache' function, and wrap the dynamic caller in <Suspense>.
No (compliance prevents cross-request sharing) → use 'use cache: private'
(experimental — not recommended for production) as a last resort, still
wrapped in <Suspense>.
Key insight: 'use cache' is for data that is the same across users. User-specific
data stays dynamic and streams through <Suspense>. Reach for 'use cache: private' only
when you cannot refactor runtime data into arguments.
Server Actions are for MUTATIONS ONLY - never for data fetching:
Purpose
Use
Example Functions
Data fetch
Server Component / 'use cache'
getProducts(), getUser(id)
Mutation
Server Action ('use server')
createProduct(), updateUser(), deletePost()
❌ WRONG: Server Action for Data Fetching
"use server"exportasyncfunctiongetProducts() {
returnawait db.products.findMany() // NO! This is not a mutation
}
"use server"exportasyncfunctiongetTheme() {
return (awaitcookies()).get("theme")?.value// NO! Just reading data
}
✅ CORRECT: Data Function + Server Component
// data/products.ts - Cached data functionexportasyncfunctiongetProducts() {
"use cache"cacheTag("products")
cacheLife("hours")
returnawait db.products.findMany()
}
// page.tsx - Server Component reads data directlyimport { cookies } from"next/headers"exportdefaultasyncfunctionPage() {
const products = awaitgetProducts()
const theme = (awaitcookies()).get("theme")?.value ?? "light"return<ProductListproducts={products}theme={theme} />
}
'use server'import { revalidateTag } from'next/cache'exportasyncfunctionupdatePost(id: string, data: FormData) {
await db.posts.update({ where: { id }, data })
revalidateTag('posts', 'max') // Serve stale, refresh in background
}
⚠️ Deprecated: The single-argument form revalidateTag('posts') is deprecated.
Always pass a profile ('max' is recommended for stale-while-revalidate) or
{ expire: <seconds> } as the second argument. For webhooks that require immediate
expiration, use revalidateTag(tag, { expire: 0 }). For immediate read-your-own-writes
in Server Actions, prefer updateTag() instead.
When to Use Each Pattern
Content Type
API
Behavior
Static
No directive
Rendered at build time
Cached
'use cache'
Included in static shell, revalidates
Dynamic
Inside <Suspense>
Streams at request time
Parameter Permutations & Subshells
Critical Concept: With Cache Components, Next.js renders ALL permutations of provided parameters to create reusable subshells.
/products/jackets/classic-bomber ← Full params (complete page)
/products/jackets/essential-windbreaker ← Full params (complete page)
/products/accessories/thermal-fleece-gloves ← Full params (complete page)
/products/jackets/[slug] ← Partial params (category subshell)
/products/accessories/[slug] ← Partial params (category subshell)
/products/[category]/[slug] ← No params (fallback shell)
Why this matters: The category subshell (/products/jackets/[slug]) can be reused for ANY jacket product, even ones not in generateStaticParams. Users navigating to an unlisted jacket get the cached category shell immediately, with product details streaming in.
generateStaticParams Requirements
With Cache Components enabled:
Must provide at least one parameter - Empty arrays now cause build errors (prevents silent production failures)
Params prove static safety - Providing params lets Next.js verify no dynamic APIs are called
Partial params create subshells - Each unique permutation generates a reusable shell
// ❌ ERROR with Cache ComponentsexportfunctiongenerateStaticParams() {
return [] // Build error: must provide at least one param
}
// ✅ CORRECT: Provide real paramsexportasyncfunctiongenerateStaticParams() {
const products = awaitgetPopularProducts()
return products.map(({ category, slug }) => ({ category, slug }))
}
Cache Key = Arguments
Arguments become part of the cache key:
// Different userId = different cache entryasyncfunctionUserData({ userId }: { userId: string }) {
'use cache'cacheTag(`user-${userId}`)
returnawaitfetchUser(userId)
}
Build-Time Feedback
Cache Components provides early feedback during development. These build errors guide you toward optimal patterns:
Error: Dynamic data outside Suspense
Error: Accessing cookies/headers/searchParams outside a Suspense boundary
Always use async - All cached functions must be async
Place 'use cache' first - Must be first statement in function body
Call cacheLife() early - Should follow 'use cache' directive
Tag meaningfully - Use semantic tags that match your invalidation needs
Extract runtime data - Move cookies()/headers() outside cached scope
Wrap dynamic content - Use <Suspense> for non-cached async components
Use 'use cache: private' as last resort - Experimental (not recommended for production). Only when runtime data cannot be extracted as params AND compliance requires no cross-request sharing
Review Checklist
When reviewing code in Cache Components projects, flag these issues:
Data fetching without 'use cache' where caching would benefit
