unstable_cache

Core Idea

API legada para cachear resultados de operações caras (ex.: queries de DB) e reutilizá-los entre requisições; substituída por use cache no Next.js 16.

Key Concepts

• Substituída: recomenda-se migrar para use cache via Cache Components.
• unstable_cache(fetchData, keyParts, options): fetchData async function que retorna Promise; keyParts array extra de chaves de identificação (necessário quando usa variáveis externas via closure não passadas como argumento); options.tags array de tags para invalidação; options.revalidate segundos até revalidar (omitir ou false = cache indefinido até revalidateTag/revalidatePath).
• Restrição: não suporta acessar fontes não-cacheadas (headers, cookies) dentro do escopo cacheado — passe esses dados como argumento vindos de fora da função.

Code Examples

import { getUser } from './data'
import { unstable_cache } from 'next/cache'

const getCachedUser = unstable_cache(async (id) => getUser(id), ['my-app-user'])

export default async function Component({ userID }) {
  const user = await getCachedUser(userID)
}

• O que demonstra: cachear uma função de fetch de usuário com uma keyPart fixa.

const getCachedUser = unstable_cache(
  async () => ({ id: userId }),
  [userId],
  { tags: ['users'], revalidate: 60 }
)

• O que demonstra: incluir valor dinâmico (userId) na cache key e configurar tags + revalidação por tempo.

Reference Tables

Version	Changes
v14.0.0	unstable_cache introduzido

Anti-patterns

• Usar em código novo com Cache Components disponível: prefira 'use cache'.
• Acessar headers/cookies dentro da função cacheada: não suportado; passe como argumento externo.

Key Takeaways

1. API legada — para projetos novos, prefira use cache com Cache Components.
2. Sempre inclua em keyParts qualquer variável de closure não passada como argumento explícito.

Connects To

• use cache: substituto recomendado.
• revalidateTag / revalidatePath: usados para invalidar o cache criado por unstable_cache.