use cache: private

The 'use cache: private' directive allows functions to access runtime request APIs like cookies(), headers(), and searchParams within a cached scope. In production, matching calls within one request can reuse the same result, but Next.js does not store it in a server cache across requests.

The client router can keep the rendered output in browser memory for the stale time configured with cacheLife. This client-side cache does not persist across page reloads.

Reach for 'use cache: private' when:

• You want to cache a function that already accesses runtime data, and refactoring to move the runtime access outside and pass values as arguments is not practical.
• You need request-specific data to be excluded from server caches that persist across production requests.

Private Cache Functions run at request time and are excluded from static shell generation. To start a private Cache Function before a component needs its result, see Preloading data.

It is not possible to configure custom cache handlers for 'use cache: private'.

For a comparison of the different cache directives, see How use cache: remote differs from use cache and use cache: private.

Usage

To use 'use cache: private', enable the cacheComponents flag in your next.config.ts file:

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

Then add 'use cache: private' to your function along with a cacheLife configuration.

Basic example

In this example, we demonstrate that you can access cookies within a 'use cache: private' scope:

import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { cacheLife, cacheTag } from 'next/cache'
 
export async function generateStaticParams() {
  return [{ id: '1' }]
}
 
export default async function ProductPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
 
  return (
    <div>
      <ProductDetails id={id} />
      <Suspense fallback={<div>Loading recommendations...</div>}>
        <Recommendations productId={id} />
      </Suspense>
    </div>
  )
}
 
async function Recommendations({ productId }: { productId: string }) {
  const recommendations = await getRecommendations(productId)
 
  return (
    <div>
      {recommendations.map((rec) => (
        <ProductCard key={rec.id} product={rec} />
      ))}
    </div>
  )
}
 
async function getRecommendations(productId: string) {
  'use cache: private'
  cacheTag(`recommendations-${productId}`)
  cacheLife({ stale: 60 })
 
  // Access cookies within private cache functions
  const sessionId = (await cookies()).get('session-id')?.value || 'guest'
 
  return getPersonalizedRecommendations(productId, sessionId)
}

Configuring the client stale time

Private Cache Functions contribute their stale time to the route's Client Cache. If a function only needs request-scoped deduplication, use cacheLife({ stale: Infinity }) to keep it from lowering the route's stale time.

Next.js uses the shortest stale time from the route's cache entries, so another cache or route setting can still set a finite value. Setting stale to Infinity does not store the private result on the server across production requests. Use a finite value when the client router should revalidate personalized output after a known interval.

Request APIs allowed in private caches

The following request-specific APIs can be used inside 'use cache: private' functions:

Version History