use cache: private

Core Idea

'use cache: private' permite acessar APIs de request runtime (cookies(), headers(), searchParams) dentro de um escopo cacheado, mas o resultado nunca é armazenado no servidor: fica só em memória do browser e não sobrevive a reloads. Use quando refatorar para passar dados runtime como argumento não é prático, ou por exigência de compliance que proíbe guardar dado no servidor.

Key Concepts

• Escopo por cliente: cache é per-browser, nunca compartilhado entre usuários (diferente de use cache e use cache: remote, que são compartilhados).
• Execução em todo render: por acessar dado runtime, a função roda em toda request no servidor e fica fora da geração do static shell.
• Sem cache handler customizável: não é possível configurar cache handlers para essa directive.
• APIs runtime permitidas: cookies(), headers(), searchParams funcionam aqui (diferente de use cache puro, onde são proibidas). connection() continua proibido em ambos.

Code Examples

import { cookies } from 'next/headers'
import { cacheLife, cacheTag } from 'next/cache'

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)
}

• O que demonstra: leitura de cookies() dentro de um escopo 'use cache: private', algo proibido em 'use cache' normal.

Reference Tables

API	Allowed in use cache	Allowed in 'use cache: private'
cookies()	No	Yes
headers()	No	Yes
searchParams	No	Yes
connection()	No	No

Anti-patterns

• Usar 'use cache: private' como cache compartilhado: não é o objetivo, cada entrada é isolada por browser e não persiste, para compartilhamento entre usuários use use cache ou use cache: remote.
• Esperar que entre no static shell: nunca acontece, por definição essa directive só roda em request time.
• stale menor que 30s: quebra o prefetch por link; menor que 5 minutos não entra no App Shell.

Key Takeaways

1. Escolha 'use cache: private' só quando não dá pra extrair o dado runtime e passar como argumento para um use cache/use cache: remote normal.
2. Sempre combine com cacheLife explícito.
3. connection() segue proibido mesmo aqui, é a única API runtime sem exceção entre as três directives de cache.

Connects To

• use cache (ch100): directive base, sem acesso a APIs runtime.
• use cache: remote (ch102): traz tabela comparativa completa das três directives de cache.