/next-cache-components

name: next-cache-components
description: Next.js 16 Cache Components guidance — PPR, use cache directive, cacheLife, cacheTag, updateTag, and migration from unstable_cache. Use when implementing partial prerendering, caching strategies, or migrating from older Next.js cache patterns.
metadata:
  priority: 6
  docs:
    - "https://nextjs.org/docs/app/getting-started/caching"
    - "https://nextjs.org/docs/app/api-reference/directives/use-cache"
  pathPatterns:
    - 'next.config.*'
    - 'app/**'
    - 'src/app/**'
    - 'apps/*/app/**'
    - 'apps/*/src/app/**'
  importPatterns:
    - "next/cache"
  bashPatterns:
    - '\bnext\s+(dev|build)\b'
  promptSignals:
    phrases:
      - "use cache"
      - "cache components"
      - "partial prerendering"
      - "PPR"
      - "cacheLife"
      - "cacheTag"
      - "updateTag"
      - "unstable_cache"
    allOf:
      - [cache, component]
      - [cache, directive]
      - [partial, prerender]
    anyOf:
      - "revalidateTag"
      - "stale"
      - "revalidate"
      - "cache profile"
    noneOf: []
    minScore: 6
  validate:
    -
      pattern: 'unstable_cache\s*\('
      message: 'unstable_cache is deprecated in Next.js 16 — use the "use cache" directive with cacheTag() and cacheLife() instead'
      severity: recommended
      upgradeToSkill: next-cache-components
      upgradeWhy: 'Guides migration from unstable_cache to use cache directive with cacheTag and cacheLife.'
    -
      pattern: '\bcacheHandler\s*:'
      message: 'cacheHandler (singular) is for ISR/route handler/image caching, not the use cache directive — for that, use cacheHandlers (plural) instead'
      severity: recommended
    -
      pattern: revalidateTag\(\s*['"][^'"]+['"]\s*\)
      message: 'Single-arg revalidateTag(tag) is deprecated in Next.js 16 — pass a cacheLife profile: revalidateTag(tag, "max")'
      severity: recommended
retrieval:
  aliases:
    - cache components
    - partial prerendering
    - PPR
    - use cache
  intents:
    - enable partial prerendering in Next.js
    - cache async data with use cache directive
    - invalidate cache with cacheTag
    - migrate from unstable_cache
  entities:
    - use cache
    - cacheLife
    - cacheTag
    - updateTag
    - revalidateTag
    - PPR
chainTo:
  -
    pattern: 'use cache'
    targetSkill: nextjs
    message: 'Cache component detected — loading Next.js best practices for RSC boundaries and data patterns alongside caching.'
    skipIfFileContains: 'next-best-practices'

Cache Components (Next.js 16+)

Cache Components enable Partial Prerendering (PPR) - mix static, cached, and dynamic content in a single route.

Enable Cache Components

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

const nextConfig: NextConfig = {
  cacheComponents: true,
}

export default nextConfig

This replaces the old `experimental.ppr` flag.

---

Three Content Types

With Cache Components enabled, content falls into three categories:

1. Static (Auto-Prerendered)

Synchronous code, imports, pure computations - prerendered at build time:

export default function Page() {
  return (
    <header>
      <h1>Our Blog</h1>  {/* Static - instant */}
      <nav>...</nav>
    </header>
  )
}

2. Cached (`use cache`)

Async data that doesn't need fresh fetches every request:

async function BlogPosts() {
  'use cache'
  cacheLife('hours')

  const posts = await db.posts.findMany()
  return <PostList posts={posts} />
}

3. Dynamic (Suspense)

Runtime data that must be fresh - wrap in Suspense:

import { Suspense } from 'react'

export default function Page() {
  return (
    <>
      <BlogPosts />  {/* Cached */}

      <Suspense fallback={<p>Loading...</p>}>
        <UserPreferences />  {/* Dynamic - streams in */}
      </Suspense>
    </>
  )
}

async function UserPreferences() {
  const theme = (await cookies()).get('theme')?.value
  return <p>Theme: {theme}</p>
}

---

`use cache` Directive

File Level

'use cache'

export default async function Page() {
  // Entire page is cached
  const data = await fetchData()
  return <div>{data}</div>
}

Component Level

export async function CachedComponent() {
  'use cache'
  const data = await fetchData()
  return <div>{data}</div>
}

Function Level

export async function getData() {
  'use cache'
  return db.query('SELECT * FROM posts')
}

---

Cache Profiles

Built-in Profiles

'use cache'                    // Default: 5m stale, 15m revalidate

'use cache: remote'           // Platform-provided cache (Redis, KV)

'use cache: private'          // For compliance, allows runtime APIs

`cacheLife()` - Custom Lifetime

import { cacheLife } from 'next/cache'

async function getData() {
  'use cache'
  cacheLife('hours')  // Built-in profile
  return fetch('/api/data')
}

Built-in profiles: `'default'`, `'seconds'`, `'minutes'`, `'hours'`, `'days'`, `'weeks'`, `'max'`

Inline Configuration

async function getData() {
  'use cache'
  cacheLife({
    stale: 3600,      // 1 hour - serve stale while revalidating
    revalidate: 7200, // 2 hours - background revalidation interval
    expire: 86400,    // 1 day - hard expiration
  })
  return fetch('/api/data')
}

---

Cache Invalidation

`cacheTag()` - Tag Cached Content

import { cacheTag } from 'next/cache'

async function getProducts() {
  'use cache'
  cacheTag('products')
  return db.products.findMany()
}

async function getProduct(id: string) {
  'use cache'
  cacheTag('products', `product-${id}`)
  return db.products.findUnique({ where: { id } })
}

`updateTag()` - Immediate Invalidation

Use when you need the cache refreshed within the same request:

'use server'

import { updateTag } from 'next/cache'

export async function updateProduct(id: string, data: FormData) {
  await db.products.update({ where: { id }, d