use cache

Core Idea

'use cache' marca uma rota, componente React ou função como cacheável, guardando o output serializado com base nos inputs. Requer a flag cacheComponents: true em next.config.ts (feature de Cache Components).

Key Concepts

Cache key: gerada a partir de Build ID (ou deploymentId), Function ID (hash da localização/assinatura), argumentos serializáveis, e HMR refresh hash (dev only). Variáveis de outer scope capturadas por closure entram na key como se fossem argumentos.
cacheLife(profile): define lifetime explícito do cache (ex. 'hours', 'max'); sem ela, usa o profile default (stale 5min client, revalidate 15min server, never expires).
cacheTag(tag) + revalidateTag/updateTag: invalidação on-demand por tag, complementar ao revalidate por tempo.
Serialização: argumentos usam serialização de React Server Components (mais restritiva); return values usam serialização de Client Components (aceita JSX). Pass-through (children, Server Actions) é permitido sem introspecção.
Constraint de request-time APIs: cookies(), headers(), searchParams não podem ser lidos dentro do escopo 'use cache', nem por uma função auxiliar chamada de dentro dele; erro next-request-in-use-cache.
In-memory cache runtime: default é LRU em memória; em serverless não persiste entre requests, em self-hosted persiste (configurável via cacheMaxMemorySize).
React.cache isolation: 'use cache' roda em escopo isolado do React.cache; valores setados fora não são visíveis dentro.

Code Examples

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

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

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

O que demonstra: função cacheada em nível de função, com lifetime explícito (cacheLife) e tag para invalidação on-demand (cacheTag).

Reference Tables

Environment	Runtime Caching Behavior
Serverless	Entradas normalmente não persistem entre requests (instância pode mudar); build-time caching funciona normal.
Self-hosted	Entradas persistem entre requests; controlar tamanho via `cacheMaxMemorySize`.

Deployment Option	Supported
Node.js server	Yes
Docker container	Yes
Static export	No
Adapters	Platform-specific

Anti-patterns

Ler cookies()/headers()/searchParams dentro de 'use cache': falha com erro next-request-in-use-cache; leia fora do escopo cacheado e passe como argumento.
Passar Promise de dado runtime como prop/via closure/Map compartilhado para dentro de 'use cache': causa hang de build (timeout de 50s) porque o cache tenta resolver dado que só existe em request-time; aguarde a Promise fora do escopo cacheado.
Usar React.cache para injetar dado num escopo 'use cache': não funciona, o escopo é isolado; use argumentos de função.
Aninhar use cache de vida curta dentro de um sem cacheLife explícito: falha o build no prerendering; sempre declare cacheLife explicitamente em cada escopo.
Omitir cacheLife: aplica o profile default silenciosamente, tornando o comportamento de cache implícito no call site.

Key Takeaways

Cached functions/components devem ser async; placement decide o escopo do cache (função vs. componente vs. arquivo/rota inteira).
Combine cacheLife (revalidação por tempo) com cacheTag+revalidateTag/updateTag (revalidação sob demanda) — não são mutuamente exclusivos.
Draft Mode desativa o cache automaticamente: toda função 'use cache' reexecuta a cada request sem persistir.
Nenhum cache directive sobrevive a um novo deploy (build/deploymentId muda a key); para persistência entre deploys use unstable_cache ou fetch cache.
Debug com NEXT_PRIVATE_DEBUG_CACHE=1 para logging verboso.

Connects To

use cache: private (ch101): variante para acessar APIs de request runtime.
use cache: remote (ch102): cache handler remoto (Redis/KV) para dados que o in-memory LRU não cobre.
Directives (ch099): visão geral de onde 'use cache' se encaixa entre as outras directives.