next-cache-components

# Cache Components (Next.js 16+) Cache Components enable Partial Prerendering (PPR) - mix static, cached, and dynamic content in a single route. ## Enable Cache Components ```ts // 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: ```tsx 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: ```tsx 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: ```tsx 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 ```tsx "use cache"; export default async function Page() { // Entire page is cached const data = await fetchData(); return <div>{data}</div>; } ``` ### Component Level ```tsx export async function CachedComponent() { "use cache"; const data = await fetchData(); return <div>{data}</div>; } ``` ### Function Level ```tsx export async function getData() { "use cache"; return db.query("SELECT * FROM posts"); } ``` --- ## Cache Profiles ### Built-in Profiles ```tsx "use cache"; // Default: 5m stale, 15m revalidate ``` ```tsx "use cache: remote"; // Platform-provided cache (Redis, KV) ``` ```tsx "use cache: private"; // For compliance, allows runtime APIs ``` ### `cacheLife()` - Custom Lifetime ```tsx import { cacheLife } from "next/cache"; async function getData() { "use cache"; cacheLife("hours"); // Built-in profile return fetch("/api/data"); } ``` Built-in profiles: `'default'`, `'minutes'`, `'hours'`, `'days'`, `'weeks'`, `'max'` ### Inline Configuration ```tsx 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 ```tsx 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: ```tsx "use server"; import { updateTag } from "next/cache"; export async function updateProduct(id: string, data: FormData) { await db.products.update({ where: { id }, data }); updateTag(`product-${id}`); // Immediate - same request sees fresh data } ``` ### `revalidateTag()` - Background Revalidation Use for stale-while-revalidate behavior: ```tsx "use server"; import { revalidateTag } from "next/cache"; export async function createPost(data: FormData) { await db.posts.create({ data }); revalidateTag("posts"); // Background - next request sees fresh data } ``` --- ## Runtime Data Constraint **Cannot** access `cookies()`, `headers()`, or `searchParams` inside `use cache`. ### Solution: Pass as Arguments ```tsx // Wrong - runtime API inside use cache async function CachedProfile() { "use cache"; const session = (await cookies()).get("session")?.value; // Error! return <div>{session}</div>; } // Correct - extract outside, pass as argument async function ProfilePage() { const session = (await cookies()).get("session")?.value; return <CachedProfile sessionId={session} />; } async function CachedProfile({ sessionId }: { sessionId: string }) { "use cache"; // sessionId becomes part of cache key automatically const data = await fetchUserData(sessionId); return <div>{data.name}</div>; } ``` ### Exception: `use cache: private` For compliance requirements when you can't refactor: ```tsx async function getData() { "use cache: private"; const session = (await cookies()).get("session")?.value; // Allowed return fetchData(session); } ``` --- ## Cache Key Generation Cache keys are automatic based on: - **Build ID** - invalidates all caches on deploy - **Function ID** - hash of function location - **Serializable arguments** - props become part of key - **Closure variables** - outer scope values included ```tsx async function Component({ userId }: { userId: string }) { const getData = async (filter: string) => { "use cache"; // Cache key = userId (closure) + filter (argument) return fetch(`/api/users/${userId}?filter=${filter}`); }; return getData("active"); } ``` --- ## Complete Example ```tsx import { cacheLife, cacheTag } from "next/cache"; import { cookies } from "next/headers"; import { Suspense } from "react"; export default function DashboardPage() { return ( <> {/* Static shell - instant from CDN */} <header> <h1>Dashboard</h1> </header> <nav>...</nav> {/* Cached - fast, revalidates hourly */} <Stats /> {/* Dynamic - streams in with fresh data */} <Suspense fallback={<NotificationsSkeleton />}> <Notifications /> </Suspense> </> ); } async function Stats() { "use cache"; cacheLife("hours"); cacheTag("dashboard-stats"); const stats = await db.stats.aggregate(); return <StatsDisplay stats={stats} />; } async function Notifications() { const userId = (await cookies()).get("userId")?.value; const notifications = await db.notifications.findMany({ where: { userId, read: false }, }); return <NotificationList items={notifications} />; } ``` --- ## Migration from Previous Versions | Old Config | Replacement | | --------------------------- | ---------------------------------- | | `experimental.ppr` | `cacheComponents: true` | | `dynamic = 'force-dynamic'` | Remove (default behavior) | | `dynamic = 'force-static'` | `'use cache'` + `cacheLife('max')` | | `revalidate = N` | `cacheLife({ revalidate: N })` | | `unstable_cache()` | `'use cache'` directive | ### Migrating `unstable_cache` to `use cache` `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: **Before (`unstable_cache`):** ```tsx import { unstable_cache } from "next/cache"; const getCachedUser = unstable_cache(async (id) => getUser(id), ["my-app-user"], { tags: ["users"], revalidate: 60, }); export default async function Page({ params }: { params: Promise<{ id: string }> }) { const { id } = await params; const user = await getCachedUser(id); return <div>{user.name}</div>; } ``` **After (`use cache`):** ```tsx import { cacheLife, cacheTag } from "next/cache"; async function getCachedUser(id: string) { "use cache"; cacheTag("users"); cacheLife({ revalidate: 60 }); return getUser(id); } export default async function Page({ params }: { params: Promise<{ id: string }> }) { const { id } = await params; const user = await getCachedUser(id); return <div>{user.name}</div>; } ``` Key differences: - **No manual cache keys** - `use cache` generates keys automatically from function arguments and closures. The `keyParts` array from `unstable_cache` is no longer needed. - **Tags** - Replace `options.tags` with `cacheTag()` calls inside the function. - **Revalidation** - Replace `options.revalidate` with `cacheLife({ revalidate: N })` or a built-in profile like `cacheLife('minutes')`. - **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. --- ## Limitations - **Edge runtime not supported** - requires Node.js - **Static export not supported** - needs server - **Non-deterministic values** (`Math.random()`, `Date.now()`) execute once at build time inside `use cache` For request-time randomness outside cache: ```tsx import { connection } from "next/server"; async function DynamicContent() { await connection(); // Defer to request time const id = crypto.randomUUID(); // Different per request return <div>{id}</div>; } ``` Sources: - [Cache Components Guide](https://nextjs.org/docs/app/getting-started/cache-components) - [use cache Directive](https://nextjs.org/docs/app/api-reference/directives/use-cache)