cache-components_skill

Overview

This skill delivers expert guidance for building Next.js Cache Components and Partial Prerendering (PPR) when cacheComponents: true is enabled. It enforces compositional caching patterns, recommends APIs like 'use cache', cacheLife(), cacheTag(), and provides concrete rules for composing static shells, cached subshells, and dynamic Suspense streams. It activates automatically by detecting cacheComponents in next.config and guides authors across server components, data fetching, and server actions.

How this skill works

At session start it checks next.config.* for cacheComponents: true and then applies Cache Components patterns proactively to all React Server Component work. It inspects component boundaries, data fetching sites, server actions, and generateStaticParams usage to recommend adding 'use cache', meaningful cacheTag(), appropriate cacheLife(), and Suspense wrappers for dynamic data. It also flags common build-time errors and suggests fixes for runtime data, invalidation, and parameter permutations.

When to use it

• Authoring React Server Components that perform I/O
• Deciding whether data can be shared across users and cached
• Implementing server actions that mutate data and need cache invalidation
• Designing pages with a static shell, cached subshells, and streaming dynamic content
• Reviewing an existing codebase for cache correctness and PPR best practices

Best practices

• Use 'use cache' for data that is identical across users; keep all cached functions async
• Call cacheLife() immediately after the 'use cache' directive to set revalidate/expire behavior
• Tag cached content with cacheTag() using semantic names to enable targeted invalidation
• After mutations call updateTag() for immediate consistency or revalidateTag() for stale-while-revalidate flows
• Keep cookies()/headers()/searchParams out of 'use cache' scope; extract runtime data and handle it inside Suspense boundaries
• Wrap any uncached or request-dependent async component in <Suspense> with a fallback

Example use cases

• Cached blog post list: add 'use cache', cacheTag('posts'), cacheLife('hours') and return static shell fast
• Product pages with generateStaticParams: pre-render param permutations to create reusable subshells and stream item details dynamically
• Server action create/update flows: perform DB write then call updateTag('posts') or revalidateTag('posts','max')
• User-specific widgets: keep dynamic inside Suspense and avoid placing request context inside cached components
• Debugging build errors: fix "uncached data outside Suspense" by either caching or wrapping in Suspense