use cache

The use cache directive allows you to mark a route, React component, or a function as cacheable. It can be used at the top of a file to indicate that all exports in the file should be cached, or inline at the top of a function or component to cache the return value. Functions and components that use use cache must be async.

Good to know:

• To use cookies or headers, read them outside cached scopes and pass values as arguments. This is the preferred pattern.
• If the in-memory cache isn't sufficient for runtime data, 'use cache: remote' allows platforms to provide a dedicated cache handler, though it requires a network roundtrip to check the cache and typically incurs platform fees.
• For compliance requirements or when you can't refactor to pass runtime data as arguments to a use cache scope, see 'use cache: private'.

Usage

use cache is a Cache Components feature. To enable it, add the cacheComponents option to your next.config.ts file:

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  cacheComponents: true,
}
 
export default nextConfig

Then, add use cache at the function, component, or file level. Cached functions and components must be async:

// Function level
export async function getData() {
  'use cache'
  const res = await fetch('https://api.example.com/data')
  const data = await res.json()
  return data
}
 
// Component level
export async function MyComponent() {
  'use cache'
  return <></>
}

When used at file level, every exported function becomes a cached function and must also be async:

// File level
'use cache'
 
export default async function Page() {
  // ...
}

How use cache works

Cache keys

A cache entry's key is generated using a serialized version of its inputs, which includes:

1. Build ID - Unique per build, changing this invalidates all cache entries. If deploymentId is configured, it overrides the build ID for cache key purposes.
2. Function ID - A secure hash of the function's location and signature in the codebase
3. Serializable arguments - Props (for components) or function arguments
4. HMR refresh hash (development only) - Invalidates cache on hot module replacement

When a cached function references variables from outer scopes, those variables are automatically captured and bound as arguments, making them part of the cache key.

async function Component({ userId }: { userId: string }) {
  const getData = async (filter: string) => {
    'use cache'
    // Cache key includes both userId (from closure) and filter (argument)
    const res = await fetch(
      `https://api.example.com/users/${userId}/data?filter=${filter}`
    )
    return res.json()
  }
 
  return getData('active')
}

In the snippet above, userId is captured from the outer scope and filter is passed as an argument, so both become part of the getData function's cache key. This means different user and filter combinations will have separate cache entries.

Good to know: When a cached function reads root parameters, only the ones it actually reads become part of its cache key.

Cache output

A cached function produces the same output for the same inputs. The first call with a given set of inputs runs the function body and stores its output. Every later call with the same inputs reuses that output, within a render pass and across requests, for as long as the entry lasts.

Outputs are stored by a cache handler, in memory by default, and last until they revalidate.

import { cacheLife } from 'next/cache'
 
export async function getOrderSummary(accountId: string) {
  'use cache'
  cacheLife('hours')
 
  const orders = await getOrders(accountId)
  const totals = await getOrderTotals(accountId)
 
  return { orders, totals }
}
 
export async function getOrders(accountId: string) {
  'use cache'
  cacheLife('hours')
 
  return db.orders.findMany({ where: { accountId } })
}
 
export async function getOrderTotals(accountId: string) {
  return db.orders.aggregate({ where: { accountId }, _sum: { amount: true } })
}

In the example above, each accountId has its own entry for getOrderSummary, holding the serialized { orders, totals } object it returns. Calls to getOrders have their own entries, keyed by the same accountId. If an earlier call, through the summary or directly, already filled one, db.orders.findMany doesn't run and those orders become part of the summary's output. See nested caching behavior for how an inner lifetime affects the entry around it.

Note that getOrderTotals is not cached. It is exported so other parts of the application can read fresh totals in an uncached scope. Inside getOrderSummary, though, the totals query only runs when that function runs following the 'hours' lifetime set there.

With Cache Components, prerendering fills the entry and keeps rendering, so this output contributes to the route's static shell and can contribute to its prefetch. A cache life too short to store safely leaves a hole that resolves at request time instead. See prerendering behavior for the thresholds.

Serialization

Arguments to cached functions and their return values must be serializable.

For a complete reference, see:

• Serializable arguments - Uses React Server Components serialization
• Serializable return types - Uses React Client Components serialization

Good to know: Arguments and return values use different serialization systems. Server Component serialization (for arguments) is more restrictive than Client Component serialization (for return values). This means you can return JSX elements but cannot accept them as arguments unless using pass-through patterns.

Supported types

Arguments:

• Primitives: string, number, boolean, null, undefined
• Plain objects: { key: value }
• Arrays: [1, 2, 3]
• Dates, Maps, Sets, TypedArrays, ArrayBuffers
• React elements (as pass-through only)

Return values:

• Same as arguments, plus JSX elements

Unsupported types

• Class instances
• Functions (except as pass-through)
• Symbols, WeakMaps, WeakSets
• URL instances

// Valid - primitives and plain objects
async function UserCard({
  id,
  config,
}: {
  id: string
  config: { theme: string }
}) {
  'use cache'
  return <div>{id}</div>
}
 
// Invalid - class instance
async function UserProfile({ user }: { user: UserClass }) {
  'use cache'
  // Error: Cannot serialize class instance
  return <div>{user.name}</div>
}

Pass-through (non-serializable arguments)

You can accept non-serializable values as long as you don't introspect them. This enables composition patterns with children and Server Actions:

async function CachedWrapper({ children }: { children: ReactNode }) {
  'use cache'
  // Don't read or modify children - just pass it through
  return (
    <div className="wrapper">
      <header>Cached Header</header>
      {children}
    </div>
  )
}
 
// Usage: children can be dynamic
export default function Page() {
  return (
    <CachedWrapper>
      <DynamicComponent /> {/* Not cached, passed through */}
    </CachedWrapper>
  )
}

You can also pass Server Actions through cached components:

async function CachedForm({ action }: { action: () => Promise<void> }) {
  'use cache'
  // Don't call action here - just pass it through
  return <form action={action}>{/* ... */}</form>
}

Constraints

Cached functions execute in an isolated environment. The following constraints ensure cache behavior remains predictable and secure.

Request-time APIs

Cached functions and components cannot access runtime APIs like cookies(), headers(), or searchParams, and the restriction follows the call stack: a helper the cached function calls that reads one of these fails the same way, with the next-request-in-use-cache error. On a dynamically rendered route this surfaces when the route runs, so it can pass next build and fail under next start. Read these values outside the cached scope and pass them as arguments.

Runtime caching considerations

While use cache is designed primarily to include uncached data in the static shell, it can also cache data at runtime using in-memory LRU (Least Recently Used) storage.

With the default in-memory handler, runtime cache behavior depends on your hosting environment:

For example, in a serverless environment, a cached function shared by two pages executes on each static shell revalidation, whereas in self-hosted or environments with persistent memory, the cached output is reused if it's still fresh.

If the default in-memory cache isn't enough, consider use cache: remote which allows platforms to provide a dedicated cache handler (like Redis or KV database). This helps reduce hits against data sources not scaled to your total traffic, though it comes with costs (storage, network latency, platform fees).

Very rarely, for compliance requirements or when you can't refactor your code to pass runtime data as arguments to a use cache scope, you might need use cache: private.

Draft Mode

When Draft Mode is enabled, all cached functions and components re-execute on every request, and results are not saved to the cache. This ensures draft content is always fresh without requiring any changes to your caching code.

You can read isEnabled from draftMode() inside a use cache scope, however, other runtime APIs like cookies() and headers() are not allowed, even when Draft Mode is active. See Passing runtime values to cached functions for the recommended pattern.

import { draftMode } from 'next/headers'
 
async function Content() {
  'use cache'
 
  const { isEnabled } = await draftMode()
  const url = isEnabled
    ? 'https://draft.example.com/content'
    : 'https://production.example.com/content'
 
  const data = await fetch(url)
  return <article>{/* ... */}</article>
}

Calling enable() or disable() inside a caching directive scope will also throw an error. Draft Mode can only be toggled in Route Handlers or Server Actions.

React.cache isolation

React.cache operates in an isolated scope inside use cache boundaries. Values stored via React.cache outside a use cache function are not visible inside it.

This means you cannot use React.cache to pass data into a use cache scope:

import { cache } from 'react'
 
const store = cache(() => ({ current: null as string | null }))
 
function Parent() {
  const shared = store()
  shared.current = 'value from parent'
  return <Child />
}
 
async function Child() {
  'use cache'
  const shared = store()
  // shared.current is null, not 'value from parent'
  // use cache has its own isolated React.cache scope
  return <div>{shared.current}</div>
}

This isolation ensures cached functions have predictable, self-contained behavior. To pass data into a use cache scope, use function arguments instead.

use cache at runtime

On the server, cache entries are stored in-memory and respect the revalidate and expire times from your cacheLife configuration. You can customize the cache storage by configuring cacheHandlers in your next.config.js file.

On the client, content from the server cache is stored in the browser's memory for the duration defined by the stale time. The client router enforces a minimum 30-second stale time, regardless of configuration.

The x-nextjs-stale-time response header communicates cache lifetime from server to client, ensuring coordinated behavior.

Revalidation

Cached functions revalidate based on the revalidate and expire times in their cacheLife profile, or on-demand through tags. These two approaches are not mutually exclusive and are often paired:

• Time-based: refresh automatically after a set duration with cacheLife.
• On-demand: invalidate after a mutation with cacheTag and revalidateTag or updateTag.

For example, a blog post that changes only when its author edits it can use a long cacheLife like max with a cacheTag, then invalidate on demand when the post is saved. A list of recent posts that updates throughout the day can use a shorter profile like hours to refresh on its own, without manual invalidation.

Time-based revalidation

Set an explicit cache lifetime with cacheLife in every use cache scope. It makes the cache behavior clear at the call site, instead of depending on the default profile or surrounding caches.

import { cacheLife } from 'next/cache'
 
async function getData() {
  'use cache'
  cacheLife('hours') // Use built-in 'hours' profile
  const res = await fetch('https://api.example.com/data')
  return res.json()
}

If you omit cacheLife, the default profile applies and the lifetime is no longer explicit at the call site:

• stale: 5 minutes (client-side)
• revalidate: 15 minutes (server-side)
• expire: never expires by time

async function getData() {
  'use cache'
  // Implicitly uses the 'default' profile
  const res = await fetch('https://api.example.com/data')
  return res.json()
}

Nesting a short-lived use cache inside one without an explicit cacheLife fails the build during prerendering. See Nested short-lived caches for the rule and fix.

On-demand revalidation

Use cacheTag, updateTag, or revalidateTag for on-demand cache invalidation:

import { cacheTag } from 'next/cache'
 
async function getProducts() {
  'use cache'
  cacheTag('products')
  const res = await fetch('https://api.example.com/products')
  return res.json()
}

'use server'
 
import { updateTag } from 'next/cache'
 
export async function updateProduct() {
  await db.products.update(...)
  updateTag('products') // Invalidates all 'products' caches
}

Both cacheLife and cacheTag integrate across client and server caching layers, meaning you configure your caching semantics in one place and they apply everywhere.

Examples

Caching function output with use cache

You can add use cache to any asynchronous function, not only to components and routes. You might want to cache a network request, a database query, or a slow computation.

export async function getData() {
  'use cache'
 
  const res = await fetch('https://api.example.com/data')
  const data = await res.json()
  return data
}

Caching a component's output with use cache

You can use use cache at the component level to cache any fetches or computations performed within that component. The cache entry will be reused as long as the serialized props produce the same value in each instance.

export async function Bookings({ type = 'haircut' }: BookingsProps) {
  'use cache'
  async function getBookingsData() {
    const response = await fetch(
      `https://api.example.com/bookings?type=${encodeURIComponent(type)}`
    )
    const data = await response.json()
    return data
  }
  return //...
}
 
interface BookingsProps {
  type: string
}

Interleaving

In React, composition with children or slots is a well-known pattern for building flexible components. When using use cache, you can continue to compose your UI in this way. Anything included as children, or other compositional slots, in the returned JSX will be passed through the cached component without affecting its cache entry.

As long as you don't directly reference any of the JSX slots inside the body of the cacheable function itself, their presence in the returned output won't affect the cache entry.

export default async function Page() {
  const uncachedData = await getData()
  return (
    // Pass compositional slots as props, e.g. header and children
    <CacheComponent header={<h1>Home</h1>}>
      {/* DynamicComponent is provided as the children slot */}
      <DynamicComponent data={uncachedData} />
    </CacheComponent>
  )
}
 
async function CacheComponent({
  header, // header: a compositional slot, injected as a prop
  children, // children: another slot for nested composition
}: {
  header: ReactNode
  children: ReactNode
}) {
  'use cache'
  const res = await fetch('https://api.example.com/cached-data')
  const cachedData = await res.json()
  return (
    <div>
      {header}
      <PrerenderedComponent data={cachedData} />
      {children}
    </div>
  )
}

You can also pass Server Actions through cached components to Client Components without invoking them inside the cacheable function.

import ClientComponent from './ClientComponent'
 
export default async function Page() {
  const performUpdate = async () => {
    'use server'
    // Perform some server-side update
    await db.update(...)
  }
 
  return <CachedComponent performUpdate={performUpdate} />
}
 
async function CachedComponent({
  performUpdate,
}: {
  performUpdate: () => Promise<void>
}) {
  'use cache'
  // Do not call performUpdate here
  return <ClientComponent action={performUpdate} />
}

'use client'
 
export default function ClientComponent({
  action,
}: {
  action: () => Promise<void>
}) {
  return <button onClick={action}>Update</button>
}

Caching a module's exports with use cache

Placing the directive at the top of a file covers every export, instead of repeating it on each one. Every exported function it covers must be async.

'use cache'
 
export async function getMonthlyTotals(accountId: string) {
  return db.orders.aggregate({ where: { accountId }, _sum: { amount: true } })
}
 
export async function getTopProducts() {
  return db.products.findMany({ orderBy: { sales: 'desc' }, take: 10 })
}

Framework function exports are covered like any other, so generateMetadata and generateStaticParams must be async in such a file.

Good to know:

• When a cached directive (use cache, use cache: private, or use cache: remote) is at the top of a file, you can import its exported functions into a Client Component and call them directly; they run on the server and return the result, similar to a Server Function. Prefer calling cached functions on the server and passing results down as props.

Caching a route segment's output with use cache

A page or layout file is a module too, so a file-level directive there follows the same rules. Each route segment is a separate entry point and is cached independently. To prerender a whole route, add use cache to the top of every segment file it renders: the page, the layout, and any parallel route slots.

'use cache'
 
export default async function Layout({ children }: { children: ReactNode }) {
  return <div>{children}</div>
}

A cached layout does not cache the children it renders, since slots pass through without affecting its entry. See Interleaving.

'use cache'
 
async function Users() {
  const res = await fetch('https://api.example.com/users')
  const users = await res.json()
  // loop through users
}
 
export default async function Page() {
  return (
    <main>
      <Users />
    </main>
  )
}

Troubleshooting

Debugging cache behavior

Verbose logging

Set NEXT_PRIVATE_DEBUG_CACHE=1 for verbose cache logging:

NEXT_PRIVATE_DEBUG_CACHE=1 npm run dev
# or for production
NEXT_PRIVATE_DEBUG_CACHE=1 npm run start

Good to know: This environment variable also logs ISR and other caching mechanisms. See Verifying correct production behavior for more details.

Console log replays

In development, console logs from cached functions appear with a Cache prefix.

Build Hangs (Cache Timeout)

If your build hangs, you're accessing Promises that resolve to uncached or runtime data, created outside a use cache boundary. The cached function waits for data that can't resolve during the build, causing a timeout after 50 seconds.

When the build timeouts you'll see this error message:

Error: Filling a cache during prerender timed out, likely because request-specific arguments such as params, searchParams, cookies() or uncached data were used inside "use cache".

Common ways this happens: passing such Promises as props, accessing them via closure, or retrieving them from shared storage (Maps).

Good to know: Directly calling cookies() or headers() inside use cache fails immediately with a different error, not a timeout.

Passing runtime data Promises as props:

import { cookies } from 'next/headers'
import { Suspense } from 'react'
 
export default function Page() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Dynamic />
    </Suspense>
  )
}
 
async function Dynamic() {
  const cookieStore = cookies()
  return <Cached promise={cookieStore} /> // Build hangs
}
 
async function Cached({ promise }: { promise: Promise<unknown> }) {
  'use cache'
  const data = await promise // Waits for runtime data during build
  return <p>..</p>
}

Await the cookies store in the Dynamic component, and pass a cookie value to the Cached component.

Shared deduplication storage:

// Problem: Map stores dynamic Promises, accessed by cached code
import { Suspense } from 'react'
 
const cache = new Map<string, Promise<string>>()
 
export default function Page() {
  return (
    <>
      <Suspense fallback={<div>Loading...</div>}>
        <Dynamic id="data" />
      </Suspense>
      <Cached id="data" />
    </>
  )
}
 
async function Dynamic({ id }: { id: string }) {
  // Stores dynamic Promise in shared Map
  cache.set(
    id,
    fetch(`https://api.example.com/${id}`).then((r) => r.text())
  )
  return <p>Dynamic</p>
}
 
async function Cached({ id }: { id: string }) {
  'use cache'
  return <p>{await cache.get(id)}</p> // Build hangs - retrieves dynamic Promise
}

Use Next.js's built-in fetch() deduplication or use separate Maps for cached and uncached contexts.

Platform Support

Learn how to configure caching when self-hosting Next.js.

Version History