Expert guidance for Next.js Cache Components and Partial Prerendering (PPR). **PROACTIVE ACTIVATION**: Use this skill automatically when working in Next.js projects that have `cacheComponents: true` in their next.config.ts/next.config.js. When this config is detected, proactively apply Cache Components patterns and best practices to all React Server Component implementations. **DETECTION**: At the start of a session in a Next.js project, check for `cacheComponents: true` in next.config. If enabled, this skill's patterns should guide all component authoring, data fetching, and caching decisions. **USE CASES**: 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, debugging cache issues, and reviewing Cache Component implementations.
Guides Next.js Cache Components implementation with 'use cache', cacheLife(), and cacheTag() for optimal Partial Prerendering.
/plugin marketplace add https://www.claudepluginhub.com/api/plugins/vercel-cache-components-claude-plugin-plugins-cache-components/marketplace.json/plugin install vercel-cache-components-claude-plugin-plugins-cache-components@cpd-vercel-cache-components-claude-plugin-plugins-cache-componentsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Auto-activation: This skill activates automatically in projects with
cacheComponents: truein next.config.
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:
Cache Components enable Partial Prerendering (PPR) - mixing static HTML shells with dynamic streaming content for optimal performance.
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.
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā Static Shell ā
ā (Sent immediately to browser) ā
ā ā
ā āāāāāāāāāāāāāāā āāāāāāāāāāāāāāā āāāāāāāāāāāāāāā ā
ā ā Header ā ā Cached ā ā Suspense ā ā
ā ā (static) ā ā Content ā ā Fallback ā ā
ā āāāāāāāāāāāāāāā āāāāāāāāāāāāāāā āāāāāāāā¬āāāāāāā ā
ā ā ā
ā āāāāāāāā¼āāāāāāā ā
ā ā Dynamic ā ā
ā ā (streams) ā ā
ā āāāāāāāāāāāāāāā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
When writing a React Server Component, ask these questions in order:
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā Does this component fetch data or perform I/O? ā
āāāāāāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā
āāāāāāāāāāāā¼āāāāāāāāāāā
ā YES ā NO ā Pure component, no action needed
āāāāāāāāāāāā¬āāāāāāāāāāā
ā
āāāāāāāāāāāāāāāāāāā¼āāāāāāāāāāāāāāāāāā
ā Does it depend on request context? ā
ā (cookies, headers, searchParams) ā
āāāāāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāā
ā
āāāāāāāāāāāāāā“āāāāāāāāāāāāā
ā ā
āāāāāā¼āāāāā āāāāāāā¼āāāāāā
ā YES ā ā NO ā
āāāāāā¬āāāāā āāāāāāā¬āāāāāā
ā ā
ā āāāāāāā¼āāāāāāāāāāāāāāāāāā
ā ā Can this be cached? ā
ā ā (same for all users?) ā
ā āāāāāāā¬āāāāāāāāāāāāāāāāāā
ā ā
ā āāāāāāāāāāāā“āāāāāāāāāāā
ā ā ā
ā āāāāāā¼āāāāā āāāāāāā¼āāāāāā
ā ā YES ā ā NO ā
ā āāāāāā¬āāāāā āāāāāāā¬āāāāāā
ā ā ā
ā ā¼ ā
ā 'use cache' ā
ā + cacheTag() ā
ā + cacheLife() ā
ā ā
āāāāāāāāāāāāāāāā¬āāāāāāāāāāāāāāāāāāāāāā
ā
ā¼
Wrap in <Suspense>
(dynamic streaming)
Key insight: The 'use cache' directive is for data that's the same across users. User-specific data stays dynamic with Suspense.
// next.config.ts
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
}
export default nextConfig
// Cached component - output included in static shell
async function CachedPosts() {
'use cache'
const posts = await db.posts.findMany()
return <PostList posts={posts} />
}
// Page with static + cached + dynamic content
export default async function BlogPage() {
return (
<>
<Header /> {/* Static */}
<CachedPosts /> {/* Cached */}
<Suspense fallback={<Skeleton />}>
<DynamicComments /> {/* Dynamic - streams */}
</Suspense>
</>
)
}
'use cache' DirectiveMarks code as cacheable. Can be applied at three levels:
// File-level: All exports are cached
'use cache'
export async function getData() {
/* ... */
}
export async function Component() {
/* ... */
}
// Component-level
async function UserCard({ id }: { id: string }) {
'use cache'
const user = await fetchUser(id)
return <Card>{user.name}</Card>
}
// Function-level
async function fetchWithCache(url: string) {
'use cache'
return fetch(url).then((r) => r.json())
}
Important: All cached functions must be async.
cacheLife() - Control Cache Durationimport { cacheLife } from 'next/cache'
async function Posts() {
'use cache'
cacheLife('hours') // Use a predefined profile
// Or custom configuration:
cacheLife({
stale: 60, // 1 min - client cache validity
revalidate: 3600, // 1 hr - start background refresh
expire: 86400, // 1 day - absolute expiration
})
return await db.posts.findMany()
}
Predefined profiles: 'default', 'seconds', 'minutes', 'hours', 'days', 'weeks', 'max'
cacheTag() - Tag for Invalidationimport { cacheTag } from 'next/cache'
async function BlogPosts() {
'use cache'
cacheTag('posts')
cacheLife('days')
return await db.posts.findMany()
}
async function UserProfile({ userId }: { userId: string }) {
'use cache'
cacheTag('users', `user-${userId}`) // Multiple tags
return await db.users.findUnique({ where: { id: userId } })
}
updateTag() - Immediate InvalidationFor read-your-own-writes semantics:
'use server'
import { updateTag } from 'next/cache'
export async function createPost(formData: FormData) {
await db.posts.create({ data: formData })
updateTag('posts') // Client immediately sees fresh data
}
revalidateTag() - Background RevalidationFor stale-while-revalidate pattern:
'use server'
import { revalidateTag } from 'next/cache'
export async function updatePost(id: string, data: FormData) {
await db.posts.update({ where: { id }, data })
revalidateTag('posts', 'max') // Serve stale, refresh in background
}
| 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 |
Critical Concept: With Cache Components, Next.js renders ALL permutations of provided parameters to create reusable subshells.
// app/products/[category]/[slug]/page.tsx
export async function generateStaticParams() {
return [
{ category: 'jackets', slug: 'classic-bomber' },
{ category: 'jackets', slug: 'essential-windbreaker' },
{ category: 'accessories', slug: 'thermal-fleece-gloves' },
]
}
Next.js renders these routes:
/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 RequirementsWith Cache Components enabled:
// ā ERROR with Cache Components
export function generateStaticParams() {
return [] // Build error: must provide at least one param
}
// ā
CORRECT: Provide real params
export async function generateStaticParams() {
const products = await getPopularProducts()
return products.map(({ category, slug }) => ({ category, slug }))
}
Arguments become part of the cache key:
// Different userId = different cache entry
async function UserData({ userId }: { userId: string }) {
'use cache'
cacheTag(`user-${userId}`)
return await fetchUser(userId)
}
Cache Components provides early feedback during development. These build errors guide you toward optimal patterns:
Error: Accessing cookies/headers/searchParams outside a Suspense boundary
Solution: Wrap dynamic components in <Suspense>:
<Suspense fallback={<Skeleton />}>
<ComponentThatUsesCookies />
</Suspense>
Error: Accessing uncached data outside Suspense
Solution: Either cache the data or wrap in Suspense:
// Option 1: Cache it
async function ProductData({ id }: { id: string }) {
'use cache'
return await db.products.findUnique({ where: { id } })
}
// Option 2: Make it dynamic with Suspense
;<Suspense fallback={<Loading />}>
<DynamicProductData id={id} />
</Suspense>
Error: Cannot access cookies/headers inside 'use cache'
Solution: Extract runtime data outside cache boundary (see "Handling Runtime Data" above).
When generating Cache Component code:
async - All cached functions must be async'use cache' first - Must be first statement in function bodycacheLife() early - Should follow 'use cache' directivecookies()/headers() outside cached scope<Suspense> for non-cached async componentsWhen cacheComponents: true is detected in the project, automatically apply these patterns:
Ask yourself: "Can this data be cached?" If yes, add 'use cache':
// Before: Uncached fetch
async function ProductList() {
const products = await db.products.findMany()
return <Grid products={products} />
}
// After: With caching
async function ProductList() {
'use cache'
cacheTag('products')
cacheLife('hours')
const products = await db.products.findMany()
return <Grid products={products} />
}
Always invalidate relevant caches after mutations:
'use server'
import { updateTag } from 'next/cache'
export async function createProduct(data: FormData) {
await db.products.create({ data })
updateTag('products') // Don't forget!
}
Structure with static shell + cached content + dynamic streaming:
export default async function Page() {
return (
<>
<StaticHeader /> {/* No cache needed */}
<CachedContent /> {/* 'use cache' */}
<Suspense fallback={<Skeleton />}>
<DynamicUserContent /> {/* Streams at runtime */}
</Suspense>
</>
)
}
Flag these issues in Cache Components projects:
'use cache' where caching would benefitcacheTag() calls (makes invalidation impossible)cacheLife() (relies on defaults which may not be appropriate)updateTag()/revalidateTag() after mutationscookies()/headers() called inside 'use cache' scope<Suspense> boundariesexport const revalidate - replace with cacheLife() in 'use cache'export const dynamic - replace with Suspense + cache boundariesgenerateStaticParams() return - must provide at least one paramThis skill should be used when the user asks to "create a hookify rule", "write a hook rule", "configure hookify", "add a hookify rule", or needs guidance on hookify rule syntax and patterns.
Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.