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.
| File | Kind | Size |
|---|---|---|
| PATTERNS.md | markdown | 4.3 KB |
| REFERENCE.md | markdown | 5.8 KB |
| SKILL.md | skill md | 8.8 KB |
| TROUBLESHOOTING.md | markdown | 3.4 KB |
TROUBLESHOOTING.md
View on GitHub# Cache diagnostics
Reproduce with the installed version and actual caching configuration.
Use Next.js development diagnostics when available: `next-devtools-mcp` reaches
the dev server's `/_next/mcp` (`get_errors`, `get_logs`, `get_page_metadata`;
`get_compilation_issues`/`compile_route` with Turbopack),
`NEXT_PRIVATE_DEBUG_CACHE=1` logs cache activity, and
`next build --debug-prerender` keeps server source maps (not for deployment).
Then verify with the production build and runtime. Build success does not
prove freshness, authorization or runtime-only helper paths.
| Symptom | Inspect before changing policy |
| --- | --- |
| Blocking/dynamic access | Where uncached I/O, unknown params or request APIs are awaited relative to Suspense |
| `next-request-in-use-cache` | The whole helper call stack, not only the visible cached function. Read outside and pass resolved values, or use a suitable private cache |
| Build stalls/timeouts | Slow/unavailable build services or a request promise passed/captured into the isolated cached scope; await request values outside |
| Repeated reads | Key inputs, handler lifetime, process/deploy identity and deliberate bypasses |
| Stale after mutation | Write completion, tag/path coverage, invalidation profile and client freshness |
| Different values across instances | Backing store and cross-instance invalidation; one-process tests cannot prove it |
| Cross-account output | Authorized identity/filter keying, global mutable state and policy changes; on Next.js 16.0.0-16.4.4 upgrade to 16.4.5+ first (16.3.8 fixed GHSA-h694-7cp9-m8p3 root-param keying and GHSA-3w37-wq28-93x7 Draft Mode fills; 16.4.1 fixes the `use cache` RCE GHSA-673q-mjm6-r5xr; 16.4.5 fixes cross-user disclosure through binary arguments GHSA-rhh4-g77r-r9qj, shared fallback shells GHSA-vvgp-ww4w-46vf and root params GHSA-vc7v-qv4w-wrv8, GHSA-mfr8-8qww-v76h) |
| Metadata or sitemap stale | Its own data loader and refresh path, not merely the page's cache |
With Cache Components, `empty-generate-static-params` means the export returned
`[]`; supply at least one real param. A `dynamicParams` compatibility error
requires removing that legacy export and using `notFound()` for rejected
unknown params. A short-lived nested-cache prerender error requires an explicit
outer `cacheLife`, including when the inner read comes from a dependency.
A timeout is not proof of user-specific data. Such data may be cached with
correctly scoped keys when policy permits. Removing caching or adding build-time
fake data can hide the actual fault.
Do not infer every internal cache hit from a route-level response header.
Instrument the relevant loader/handler without logging sensitive arguments.
Measure cold/warm paths and inspect returned content after an actual write.
For request-only work, keep a useful fallback boundary. For short-lived cache
holes, check the installed lifetime thresholds. Avoid broad catch blocks that
swallow framework control-flow exceptions.
Exercise direct load, client navigation, listed/unlisted params and a second
identity as applicable. Check the deployed environment when local lifetime,
storage or proxy behavior differs.
Relevant official references:
[use cache](https://nextjs.org/docs/app/api-reference/directives/use-cache),
[cacheLife](https://nextjs.org/docs/app/api-reference/functions/cacheLife),
[caching](https://nextjs.org/docs/app/getting-started/caching),
[MCP diagnostics](https://nextjs.org/docs/app/guides/mcp).
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: 322k | 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: 198k | 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: 198k | 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: 198k | Updated | Claude CodeCodex | Verified | Install |