Next Cache Components

1---
2name: next-cache-components
3description: Next.js 16 Cache Components - PPR, use cache directive, cacheLife, cacheTag, updateTag
4---
5 
6# Cache Components (Next.js 16+)
7 
8Cache Components enable Partial Prerendering (PPR) - mix static, cached, and dynamic content in a single route.
9 
10## Enable Cache Components
11 
12```ts
13// next.config.ts
14import type { NextConfig } from 'next'
15 
16const nextConfig: NextConfig = {
17  cacheComponents: true,
18}
19 
20export default nextConfig
21```
22 
23This replaces the old `experimental.ppr` flag.
24 
25---
26 
27## Three Content Types
28 
29With Cache Components enabled, content falls into three categories:
30 
31### 1. Static (Auto-Prerendered)
32 
33Synchronous code, imports, pure computations - prerendered at build time:
34 
35```tsx
36export default function Page() {
37  return (
38    <header>
39      <h1>Our Blog</h1>  {/* Static - instant */}
40      <nav>...</nav>
41    </header>
42  )
43}
44```
45 
46### 2. Cached (`use cache`)
47 
48Async data that doesn't need fresh fetches every request:
49 
50```tsx
51async function BlogPosts() {
52  'use cache'
53  cacheLife('hours')
54 
55  const posts = await db.posts.findMany()
56  return <PostList posts={posts} />
57}
58```
59 
60### 3. Dynamic (Suspense)
61 
62Runtime data that must be fresh - wrap in Suspense:
63 
64```tsx
65import { Suspense } from 'react'
66 
67export default function Page() {
68  return (
69    <>
70      <BlogPosts />  {/* Cached */}
71 
72      <Suspense fallback={<p>Loading...</p>}>
73        <UserPreferences />  {/* Dynamic - streams in */}
74      </Suspense>
75    </>
76  )
77}
78 
79async function UserPreferences() {
80  const theme = (await cookies()).get('theme')?.value
81  return <p>Theme: {theme}</p>
82}
83```
84 
85---
86 
87## `use cache` Directive
88 
89### File Level
90 
91```tsx
92'use cache'
93 
94export default async function Page() {
95  // Entire page is cached
96  const data = await fetchData()
97  return <div>{data}</div>
98}
99```
100 
101### Component Level
102 
103```tsx
104export async function CachedComponent() {
105  'use cache'
106  const data = await fetchData()
107  return <div>{data}</div>
108}
109```
110 
111### Function Level
112 
113```tsx
114export async function getData() {
115  'use cache'
116  return db.query('SELECT * FROM posts')
117}
118```
119 
120---
121 
122## Cache Profiles
123 
124### Built-in Profiles
125 
126```tsx
127'use cache'                    // Default: 5m stale, 15m revalidate
128```
129 
130```tsx
131'use cache: remote'           // Platform-provided cache (Redis, KV)
132```
133 
134```tsx
135'use cache: private'          // For compliance, allows runtime APIs
136```
137 
138### `cacheLife()` - Custom Lifetime
139 
140```tsx
141import { cacheLife } from 'next/cache'
142 
143async function getData() {
144  'use cache'
145  cacheLife('hours')  // Built-in profile
146  return fetch('/api/data')
147}
148```
149 
150Built-in profiles: `'default'`, `'minutes'`, `'hours'`, `'days'`, `'weeks'`, `'max'`
151 
152### Inline Configuration
153 
154```tsx
155async function getData() {
156  'use cache'
157  cacheLife({
158    stale: 3600,      // 1 hour - serve stale while revalidating
159    revalidate: 7200, // 2 hours - background revalidation interval
160    expire: 86400,    // 1 day - hard expiration
161  })
162  return fetch('/api/data')
163}
164```
165 
166---
167 
168## Cache Invalidation
169 
170### `cacheTag()` - Tag Cached Content
171 
172```tsx
173import { cacheTag } from 'next/cache'
174 
175async function getProducts() {
176  'use cache'
177  cacheTag('products')
178  return db.products.findMany()
179}
180 
181async function getProduct(id: string) {
182  'use cache'
183  cacheTag('products', `product-${id}`)
184  return db.products.findUnique({ where: { id } })
185}
186```
187 
188### `updateTag()` - Immediate Invalidation
189 
190Use when you need the cache refreshed within the same request:
191 
192```tsx
193'use server'
194 
195import { updateTag } from 'next/cache'
196 
197export async function updateProduct(id: string, data: FormData) {
198  await db.products.update({ where: { id }, data })
199  updateTag(`product-${id}`)  // Immediate - same request sees fresh data
200}
201```
202 
203### `revalidateTag()` - Background Revalidation
204 
205Use for stale-while-revalidate behavior:
206 
207```tsx
208'use server'
209 
210import { revalidateTag } from 'next/cache'
211 
212export async function createPost(data: FormData) {
213  await db.posts.create({ data })
214  revalidateTag('posts')  // Background - next request sees fresh data
215}
216```
217 
218---
219 
220## Runtime Data Constraint
221 
222**Cannot** access `cookies()`, `headers()`, or `searchParams` inside `use cache`.
223 
224### Solution: Pass as Arguments
225 
226```tsx
227// Wrong - runtime API inside use cache
228async function CachedProfile() {
229  'use cache'
230  const session = (await cookies()).get('session')?.value  // Error!
231  return <div>{session}</div>
232}
233 
234// Correct - extract outside, pass as argument
235async function ProfilePage() {
236  const session = (await cookies()).get('session')?.value
237  return <CachedProfile sessionId={session} />
238}
239 
240async function CachedProfile({ sessionId }: { sessionId: string }) {
241  'use cache'
242  // sessionId becomes part of cache key automatically
243  const data = await fetchUserData(sessionId)
244  return <div>{data.name}</div>
245}
246```
247 
248### Exception: `use cache: private`
249 
250For compliance requirements when you can't refactor:
251 
252```tsx
253async function getData() {
254  'use cache: private'
255  const session = (await cookies()).get('session')?.value  // Allowed
256  return fetchData(session)
257}
258```
259 
260---
261 
262## Cache Key Generation
263 
264Cache keys are automatic based on:
265- **Build ID** - invalidates all caches on deploy
266- **Function ID** - hash of function location
267- **Serializable arguments** - props become part of key
268- **Closure variables** - outer scope values included
269 
270```tsx
271async function Component({ userId }: { userId: string }) {
272  const getData = async (filter: string) => {
273    'use cache'
274    // Cache key = userId (closure) + filter (argument)
275    return fetch(`/api/users/${userId}?filter=${filter}`)
276  }
277  return getData('active')
278}
279```
280 
281---
282 
283## Complete Example
284 
285```tsx
286import { Suspense } from 'react'
287import { cookies } from 'next/headers'
288import { cacheLife, cacheTag } from 'next/cache'
289 
290export default function DashboardPage() {
291  return (
292    <>
293      {/* Static shell - instant from CDN */}
294      <header><h1>Dashboard</h1></header>
295      <nav>...</nav>
296 
297      {/* Cached - fast, revalidates hourly */}
298      <Stats />
299 
300      {/* Dynamic - streams in with fresh data */}
301      <Suspense fallback={<NotificationsSkeleton />}>
302        <Notifications />
303      </Suspense>
304    </>
305  )
306}
307 
308async function Stats() {
309  'use cache'
310  cacheLife('hours')
311  cacheTag('dashboard-stats')
312 
313  const stats = await db.stats.aggregate()
314  return <StatsDisplay stats={stats} />
315}
316 
317async function Notifications() {
318  const userId = (await cookies()).get('userId')?.value
319  const notifications = await db.notifications.findMany({
320    where: { userId, read: false }
321  })
322  return <NotificationList items={notifications} />
323}
324```
325 
326---
327 
328## Migration from Previous Versions
329 
330| Old Config | Replacement |
331|-----------|-------------|
332| `experimental.ppr` | `cacheComponents: true` |
333| `dynamic = 'force-dynamic'` | Remove (default behavior) |
334| `dynamic = 'force-static'` | `'use cache'` + `cacheLife('max')` |
335| `revalidate = N` | `cacheLife({ revalidate: N })` |
336| `unstable_cache()` | `'use cache'` directive |
337 
338### Migrating `unstable_cache` to `use cache`
339 
340`unstable_cache` has been replaced by the `use cache` directive in Next.js 16. When `cacheComponents` is enabled, convert `unstable_cache` calls to `use cache` functions:
341 
342**Before (`unstable_cache`):**
343 
344```tsx
345import { unstable_cache } from 'next/cache'
346 
347const getCachedUser = unstable_cache(
348  async (id) => getUser(id),
349  ['my-app-user'],
350  {
351    tags: ['users'],
352    revalidate: 60,
353  }
354)
355 
356export default async function Page({ params }: { params: Promise<{ id: string }> }) {
357  const { id } = await params
358  const user = await getCachedUser(id)
359  return <div>{user.name}</div>
360}
361```
362 
363**After (`use cache`):**
364 
365```tsx
366import { cacheLife, cacheTag } from 'next/cache'
367 
368async function getCachedUser(id: string) {
369  'use cache'
370  cacheTag('users')
371  cacheLife({ revalidate: 60 })
372  return getUser(id)
373}
374 
375export default async function Page({ params }: { params: Promise<{ id: string }> }) {
376  const { id } = await params
377  const user = await getCachedUser(id)
378  return <div>{user.name}</div>
379}
380```
381 
382Key differences:
383- **No manual cache keys** - `use cache` generates keys automatically from function arguments and closures. The `keyParts` array from `unstable_cache` is no longer needed.
384- **Tags** - Replace `options.tags` with `cacheTag()` calls inside the function.
385- **Revalidation** - Replace `options.revalidate` with `cacheLife({ revalidate: N })` or a built-in profile like `cacheLife('minutes')`.
386- **Dynamic data** - `unstable_cache` did not support `cookies()` or `headers()` inside the callback. The same restriction applies to `use cache`, but you can use `'use cache: private'` if needed.
387 
388---
389 
390## Limitations
391 
392- **Edge runtime not supported** - requires Node.js
393- **Static export not supported** - needs server
394- **Non-deterministic values** (`Math.random()`, `Date.now()`) execute once at build time inside `use cache`
395 
396For request-time randomness outside cache:
397 
398```tsx
399import { connection } from 'next/server'
400 
401async function DynamicContent() {
402  await connection()  // Defer to request time
403  const id = crypto.randomUUID()  // Different per request
404  return <div>{id}</div>
405}
406```
407 
408Sources:
409- [Cache Components Guide](https://nextjs.org/docs/app/getting-started/cache-components)
410- [use cache Directive](https://nextjs.org/docs/app/api-reference/directives/use-cache)
411- [unstable_cache (legacy)](https://nextjs.org/docs/app/api-reference/functions/unstable_cache)
412