laguagu/claude-code-nextjs-skills / skills/cache-components
cache-components
VerifiedExpert 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, instant navigation validation, 'use cache: private', pass-through/interleaving patterns, GET Route Handler caching, debugging cache issues, and reviewing Cache Component implementations.
Cache Components
Keep the project's caching mode unless migration is requested. Confirm the
installed Next.js version and cacheComponents/partialPrefetching configuration before applying
these patterns. Use Cache Components on next 16.4.5+: 16.0.0–16.4.0 allow
unauthenticated RCE through use cache functions returning typed arrays
(GHSA-673q-mjm6-r5xr; no workaround, upgrade even without such functions), and
releases through 16.4.4 can leak or poison cached output across users
(GHSA-rhh4-g77r-r9qj binary arguments, GHSA-vvgp-ww4w-46vf shared fallback
shells, GHSA-vc7v-qv4w-wrv8 and GHSA-mfr8-8qww-v76h root params).
Flag an affected install before cache work.
Read the relevant guide in node_modules/next/dist/docs/ first (bundled since
16.2; in a monorepo, use the app's own next package). Web paths map to files
with numbered folders, so find them by name: .../functions/cacheLife is
01-app/03-api-reference/04-functions/cacheLife.md. Under 01-app/, start
with 02-guides/migrating-to-cache-components.md,
01-getting-started/08-caching.md and 02-guides/instant-navigation.md.
Error pages under /docs/messages are not bundled; next dev/next build
print the fix options inline. Without local docs, use the
official caching docs.
Exact exports and signatures are also in node_modules/next/cache.d.ts.
For static-output and staged-deferral questions in 16.4+, find the installed
ensureStatic route-segment reference and navigation/prefetch function
references by name.
The goal is a useful prerendered shell with freshness and authorization rules that remain correct after mutations, deploys and client navigation.
Facts older examples get wrong
- Next.js 16 enables the mode with top-level
cacheComponents: true. It replacesexperimental.dynamicIO,experimental.useCacheandexperimental.ppr;cacheLife/cacheTagimport fromnext/cachewithoutunstable_. In 16.4, setpartialPrefetchingexplicitly: leaving it unset warns; recommendedcreate-next-appdefaults enable both flags. - With it enabled, segment exports
dynamic,revalidate,fetchCache,dynamicParamsandruntime(even'nodejs') are errors; only the default Node.js runtime is supported.revalidate = NbecomescacheLife(nearest or custom profile) insideuse cache;force-dynamicandfetchCacheare unnecessary; fetchnext: { revalidate, tags }becomescacheLife/cacheTagin ause cachefunction; request data goes under Suspense;dynamicParams = falsebecomesnotFound()for unknown params. - Existing
fetchandunstable_cachecaching still works as a separate layer, so do not mechanically rewrite every read. Its persistence across deployments and instances depends on retained/shared storage; self-hosted instances do not share it by default.use cacheis in-memory by default; even a durable handler cannot reuse entries when the build/deployment ID changes. generateStaticParamsmust return at least one param:[]fails the build, and removing the export renders the route on every request.revalidate: 0orexpireunder 5 minutes makes a request-time hole instead of prerendered output; of the presets onlysecondsdoes. 16.3 addsstalethresholds (under 30 s: not prerendered; under 5 min: not in the App Shell).- Synchronous
new Date(),Math.random()orcrypto.randomUUID()during prerender is an error: capture it inuse cache, or defer withawait io()(next/cache, 16.3+) orawait connection()(next/server) under Suspense. use cache: privatewas experimental through 16.2. It runs at request time, stays out of the static shell and accepts no custom handler.export const instant(16.3;unstable_instantin 16.2) opts a segment into instant-navigation validation. Since 16.3, every Page/Default segment is implicitly validated innext devonly (dev overlay) at the default level; build validation requiresexperimental.instantInsights.validationLevelset toexperimental-errororexperimental-manual-error(16.2unstable_instantalso validated at build). Test navigations with@next/playwrightinstant().instant = falsepermits a blocking route; it does not clear synchronous-IO errors.
For whole-app adoption of Cache Components or Partial Prefetching, use the
official workflow skills listed in the installed 01-app/02-guides/ai-agents.md
(from vercel/next.js skills/); the bundled 02-guides/migrating-to-cache-components.md
and adopting-partial-prefetching.md cover the same steps.
Shape of one route
app/posts/page.tsx, checked against next 16.3.8 with cacheComponents: true
(tsc --noEmit, next build, the action under next start). @/lib/* is
project code.
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { cacheLife, cacheTag, updateTag } from 'next/cache'
import { insertPost, listPosts } from '@/lib/posts' // project code
import { requireEditor } from '@/lib/auth' // throws unless the session may edit
async function getPosts() {
'use cache' // shared entry: no cookies/headers/searchParams inside
cacheLife('hours')
cacheTag('posts')
return listPosts()
}
async function Theme() {
const theme = (await cookies()).get('theme')?.value // request-time, outside the cache
return <p>Theme: {theme ?? 'system'}</p>
}
async function addPost(formData: FormData) {
'use server'
await requireEditor()
const title = String(formData.get('title') ?? '').trim()
if (!title) return
await insertPost(title)
updateTag('posts') // Server Actions only; the next read waits for fresh data
}
export default async function Page() {
const posts = await getPosts() // cached, so it can be part of the static shell
return (
<>
<ul>{posts.map((p) => <li key={p.id}>{p.title}</li>)}</ul>
<Suspense fallback={<p>Theme: …</p>}><Theme /></Suspense>
<form action={addPost}><input name="title" /><button>Add</button></form>
</>
)
}
Decide the boundary
- Cache reusable results when the product's freshness and data policy permit. Static content needs no directive just to be static.
- A plain
use cachescope cannot read cookies, headers, searchParams or callconnection(), including indirectly through helpers. Read those outside and pass authorized, serializable values. Account/tenant IDs must participate in the cache key when output depends on them. On a dynamically rendered route, thenext-request-in-use-cacheerror can passnext buildand surface only undernext start. - Keep uncached I/O and request-only content below appropriate Suspense boundaries. Suspense supplies fallback UI; it does not itself make synchronous work dynamic.
- Evaluate private/remote variants against installed docs and deployment handlers. Private caching is not a compliance guarantee; remote caching is not a consistency protocol.
Define freshness and invalidation
Choose lifetimes from actual acceptable staleness. Named profiles can be overridden by the project; read its config before assuming a duration.
Use tags when invalidation must reach the same entity across routes, path invalidation for route-specific output, or expiry where that meets the contract. Authenticate, authorize and validate before mutations. Invalidate only affected cached data:
updateTag: immediate expiry/read-your-writes, Server Actions only.revalidateTag(tag, 'max'): stale-while-revalidate on a later visit.revalidateTag(tag, { expire: 0 }): immediate expiry where a webhook/Route Handler needs it. The one-argument form is deprecated.
These tag APIs can also apply to tagged fetch data; their availability does not by itself mean Cache Components is enabled.
Read for the problem
- API boundaries: keys, serialization, lifetimes, handlers and route APIs.
- Composition: tenant isolation, nested caches, pass-through and dynamic params.
- Troubleshooting: diagnose blocking, stale or inconsistent output.
Run the production build, then exercise cold/direct navigation, client
navigation, the relevant mutation and subsequent read under next start.
Check tenant isolation and multi-instance invalidation when applicable.
A passing build cannot establish those behaviors.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |