Skip to main content
skill CX Codex

cache-components · sangrokjung — Claude Code skill: Next.js Cache Components, PPR

The skill teaches the agent to apply Cache Components and Partial Prerendering in Next.js: 'use cache' directive, cache lifetimes with cacheLife(), tag-based invalidation.

MIT ★ 880 updated 2026-09-03

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sangrokjung/claude-forge --skill cache-components -a claude-code
Open on GitHub

What cache-components does

The skill activates automatically when cacheComponents: true is present in next.config.ts. The agent starts applying Cache Components patterns when writing React Server Components, configuring data caching, and optimizing boundaries between static and dynamic content. Inside: a decision tree for picking a caching strategy, examples of 'use cache' at file, component, and function level, working with cacheLife() to control cache duration and cacheTag() for tag-based invalidation.

Cache Components replace the old export const revalidate and export const dynamic with compositional code: static HTML shell, cached blocks, and dynamic parts with streaming. All cached functions must be async. The skill provides commands to check the project config, component templates with <Suspense>, and rules for when caching is possible (data is the same for all users) and when dynamics are needed (dependency on cookies, headers, searchParams).

What it helps with

  • implement Partial Prerendering in Next.js with block-level caching
  • replace export const revalidate with 'use cache' and cacheLife()
  • set up tag-based cache invalidation via cacheTag() and revalidateTag()
  • split static shell, cached content, and dynamic parts with <Suspense>
  • choose a caching strategy for a React Server Component using the decision tree

Example prompts for the agent

  • Check if cacheComponents is enabled in next.config.ts and add 'use cache' to the CachedPosts component
  • Configure caching for fetchUser() with cacheLife('hours') and tag it user-data
  • Wrap <DynamicComments> in <Suspense> and explain why this block is not cached

How to install cache-components

1Skills CLI (Vercel)

npx skills add sangrokjung/claude-forge --skill cache-components -a claude-code

2Manually: put the files in place

~/.claude/skills/cache-components/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/cache-components/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about cache-components

How to install cache-components in Claude Code?

Run npx skills add sangrokjung/claude-forge --skill cache-components -a claude-code. The file will land in ~/.claude/skills/cache-components/SKILL.md.

What does the cache-components skill do?

It teaches the agent to apply Cache Components and Partial Prerendering in Next.js: 'use cache' directive, cacheLife() for duration, cacheTag() for invalidation, splitting static, cached, and dynamic content with <Suspense>.

When does cache-components activate automatically?

The skill triggers when cacheComponents: true is found in the project's next.config.ts or next.config.js. The agent checks the config at the start of a session and applies Cache Components patterns when working with Server Components.

Source text

SKILL.md · MIT
---
name: cache-components
description: |
  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.
---

# Next.js Cache Components

> **Auto-activation**: This skill activates automatically in projects with `cacheComponents: true` in next.config.

## Project Detection

When starting work in a Next.js project, check if Cache Components are enabled:

```bash
# 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.

## 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.

## Core Concept

```
┌─────────────────────────────────────────────────────┐
│                   Static Shell                       │
│  (Sent immediately to browser)                       │
│                                                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │
│  │   Header    │  │  Cached     │  │  Suspense   │  │
│  │  (static)   │  │  Content    │  │  Fallback   │  │
│  └─────────────┘  └─────────────┘  └──────┬──────┘  │
│                                           │         │
│                                    ┌──────▼──────┐  │
│                                    │  Dynamic    │  │
│                                    │  (streams)  │  │
│                                    └─────────────┘  │
└─────────────────────────────────────────────────────┘
```

## Mental Model: The Caching Decision Tree

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.

## Quick Start

### Enable Cache Components

```typescript
// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true,
}

export default nextConfig
```

### Basic Usage

```tsx
// 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>
    </>
  )
}
```

## Core APIs

### 1. `'use cache'` Directive

Marks code as cacheable. Can be applied at three levels:

```tsx
// 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`.

### 2. `cacheLife()` - Control Cache Duration

```tsx
import { 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'`

### 3. `cacheTag()` - Tag for Invalidation

```tsx
import { 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 } })
}
```

### 4. `updateTag()` - Immediate Invalidation

For **read-your-own-writes** semantics:

```tsx
'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
}
```

### 5. `revalidateTag()` - Background Revalidation

For stale-while-revalidate pattern:

```tsx
'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
}
```

## 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.

```tsx
// 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` Requirements

With Cache Components enabled:

1. **Must provide at least one parameter** - Empty arrays now cause build errors (prevents silent production failures)
2. **Params prove static safety** - Providing params lets Next.js verify no dynamic APIs are called
3. **Partial params create subshells** - Each unique permutation generates a reusable shell

```tsx
// ❌ 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 }))
}
```

## Cache Key = Arguments

Arguments become part of the cache key:

```tsx
// Different userId = different cache entry
async function UserData({ userId }: { userId: string }) {
  'use cache'
  cacheTag(`user-${userId}`)

  return await fetchUser(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
```

**Solution**: Wrap dynamic components in `<Suspense>`:

```tsx
<Suspense fallback={<Skeleton />}>
  <ComponentThatUsesCookies />
</Suspense>
```

### Error: Uncached data outside Suspense

```
Error: Accessing uncached data outside Suspense
```

**Solution**: Either cache the data or wrap in Suspense:

```tsx
// 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: Request data inside cache

```
Error: Cannot access cookies/headers inside 'use cache'
```

**Solution**: Extract runtime data outside cache boundary (see "Handling Runtime Data" above).

## Additional Resources

- For complete API reference, see [REFERENCE.md](REFERENCE.md)
- For common patterns and recipes, see [PATTERNS.md](PATTERNS.md)
- For debugging and troubleshooting, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md)

## Code Generation Guidelines

When generating Cache Component code:

1. **Always use `async`** - All cached functions must be async
2. **Place `'use cache'` first** - Must be first statement in function body
3. **Call `cacheLife()` early** - Should follow `'use cache'` directive
4. **Tag meaningfully** - Use semantic tags that match your invalidation needs
5. **Extract runtime data** - Move `cookies()`/`headers()` outside cached scope
6. **Wrap dynamic content** - Use `<Suspense>` for non-cached async components

---

## Proactive Application (When Cache Components Enabled)

When `cacheComponents: true` is detected in the project, **automatically apply these patterns**:

### When Writing Data Fetching Components

Ask yourself: "Can this data be cached?" If yes, add `'use cache'`:

```tsx
// 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} />
}
```

### When Writing Server Actions

Always invalidate relevant caches after mutations:

```tsx
'use server'
import { updateTag } from 'next/cache'

export async function createProduct(data: FormData) {
  await db.products.create({ data })
  updateTag('products') // Don't forget!
}
```

### When Composing Pages

Structure with static shell + cached content + dynamic streaming:

```tsx
export default async function Page() {
  return (
    <>
      <StaticHeader /> {/* No cache needed */}
      <CachedContent /> {/* 'use cache' */}
      <Suspense fallback={<Skeleton />}>
        <DynamicUserContent /> {/* Streams at runtime */}
      </Suspense>
    </>
  )
}
```

### When Reviewing Code

Flag these issues in Cache Components projects:

- [ ] Data fetching without `'use cache'` where caching would benefit
- [ ] Missing `cacheTag()` calls (makes invalidation impossible)
- [ ] Missing `cacheLife()` (relies on defaults which may not be appropriate)
- [ ] Server Actions without `updateTag()`/`revalidateTag()` after mutations
- [ ] `cookies()`/`headers()` called inside `'use cache'` scope
- [ ] Dynamic components without `<Suspense>` boundaries
- [ ] **DEPRECATED**: `export const revalidate` - replace with `cacheLife()` in `'use cache'`
- [ ] **DEPRECATED**: `export const dynamic` - replace with Suspense + cache boundaries
- [ ] Empty `generateStaticParams()` return - must provide at least one param

© sangrokjung · MIT · sangrokjung/claude-forge

Similar skills

All skills for Frontend and UI →

cache-components by other authors comes first.

cache-components laguagu A skill for mastering Next.js Cache Components and Partial Prerendering in version 16.4+. Advises on the use cache directive, setting cache lifetime with cacheLife(), tagging data with cacheTag(), and invalidating via updateTag(). CX Codex +1 222installs next-cache-components official Vercel Labs next-cache-components is a Codex skill for Cache Components in Next.js 16+. It activates for PPR work, caching changes, or migrations from unstable_cache. CX Codex GP ChatGPT +1 4installs sanity-live-cache-components sanity-io sanity-live-cache-components connects next-sanity to Next.js Cache Components: sanityFetch behind one shared 'use cache' boundary, with <SanityLive> keeping cached pages fresh. CX Codex +1 602installs react-server-components-framework OrchestKit The react-server-components-framework skill guides server-first Next.js apps with React Server Components, the App Router, caching, streaming SSR, and Server Actions. CX Codex +1 227installs server-components davepoon This skill explains React Server Components in Next.js, including client boundaries, composition patterns, and data fetching choices. CX Codex +1 158installs next-cache-components-optimizer vercel next-cache-components-optimizer optimizes Next.js App Shell UI on hard and soft navigations. It sets up failing Playwright instant() checks and guides routes to green. CX Codex +1 22,000installs nextjs PyModel Skill for Claude Code, Codex, and Cursor enforces Next.js 16 App Router standards. It guides caching strategies, server components, and routing patterns. CX Codex +1 621installs

From the same set44

The whole set →
escalation-fixer escalation-fixer — a last-resort subagent for Claude that takes over after narrower build fixes have failed and is allowed to restructure the project to get it green. CX Codex ★ 880repo stars e2e The e2e command for Claude Code generates and runs Playwright end-to-end tests across browsers, capturing screenshots, traces, and reports. CX Codex +1 ★ 880repo stars skill-factory The skill-factory skill reviews work from a session, spots repeatable patterns, and turns selected ones into Claude Code skills. Use it to capture a workflow for reuse. CX Codex +1 ★ 880repo stars skeptical-auditor skeptical-auditor audits another agent's claim that everything passed: reruns the steps and checks the real exit codes. For the case where the agent graded its own work. CX Codex ★ 880repo stars api-error-recovery api-error-recovery defines an unattended session recovery setup for Claude Code after retryable API failures, timeouts, and 529 server errors. CX Codex +1 ★ 880repo stars loop-forge loop-forge is a Claude Code skill that turns recurring tasks into reusable slash commands with an independent output check and a run limit. CX Codex +1 ★ 880repo stars security-compliance security-compliance guides you through defense-in-depth architecture, threat modeling, and audit readiness for frameworks like SOC2, ISO27001, and GDPR. CX Codex +1 ★ 880repo stars claude-forge claude-forge — an agent, command and hook setup for Claude: tests first, code and security review, build error hunting, Lighthouse audits. ★ 880repo stars

Project sponsors

Companies that keep this analytics open