cacheHandler

Core Idea

Substitui o cache padrão do Next.js (ISR, route handlers, imagens otimizadas) por armazenamento externo (Redis, Memcached etc.), útil para persistir cache ou compartilhá-lo entre múltiplos containers/instâncias.

Key Concepts

• cacheHandler (singular): usado pelo Next.js para operações de cache no servidor (ISR, respostas de route handler, otimização de imagem). NÃO é usado por diretivas 'use cache' (use cacheHandlers, plural, para isso).
• cacheMaxMemorySize: separado de ambos; dimensiona o cache em memória. Setar 0 desabilita o cache em memória padrão.
• get(key, ctx): retorna o valor em cache ou null. ctx.kind indica o tipo: 'APP_PAGE', 'APP_ROUTE', 'PAGES', 'FETCH', 'IMAGE'.
• set(key, data, ctx): grava o valor; ctx inclui tags. Retorna Promise<void>.
• revalidateTag(tag): revalida por tag(s); revalidatePath é uma camada de conveniência sobre isso.
• resetRequestCache(): reseta o cache em memória temporário de uma única request.
• images.customCacheHandler: flag que habilita o cacheHandler também para cache de imagem otimizada (kind: 'IMAGE', dados incluem buffer, etag, extension, revalidate).

Code Examples

module.exports = {
  cacheHandler: require.resolve('./cache-handler.js'),
  cacheMaxMemorySize: 0, // desabilita cache em memória padrão
}

• O que demonstra: como apontar para um cache handler customizado e desligar o cache em memória padrão.

Reference Tables

Deployment Option	Suportado
Node.js server	Sim
Docker container	Sim
Static export	Não
Adapters	Depende da plataforma

Key Takeaways

1. Use cacheHandler para compartilhar cache ISR entre múltiplos containers/instâncias (ex.: Redis).
2. cacheHandler (ISR/route handlers/imagens) é distinto de cacheHandlers (diretiva 'use cache').
3. Desde v16.2.0, cacheHandler também cobre cache de otimização de imagem via images.customCacheHandler.
4. Não funciona com output: 'export' (static export).

Connects To

• cacheComponents / 'use cache': usa cacheHandlers (plural), configuração separada.
• self-hosting guide: exemplo completo de cache handler customizado.