staleTimes

Core Idea

Feature experimental que habilita cache de segmentos de página no Client Cache, com tempos de invalidação configuráveis, diferenciando páginas dinâmicas de estáticas/prefetchadas.

Key Concepts

• experimental.staleTimes: objeto { dynamic, static }, valores em segundos.
• dynamic: usado quando a página não é estaticamente gerada nem totalmente prefetchada (ex.: sem prefetch={true}). Default: 0 (sem cache).
• static: usado para páginas estaticamente geradas, ou quando <Link prefetch={true}>, ou via router.prefetch. Default: 5 minutos.
• Não afeta [partial rendering](conceito de client-side transitions): layouts compartilhados não são refetchados a cada navegação, só o segmento de página que muda.
• Não muda o comportamento de back/forward cache (evita layout shift e perda de scroll position).
• [Loading boundaries](file convention loading) são consideradas reutilizáveis pelo período static definido aqui.

Code Examples

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    staleTimes: { dynamic: 30, static: 180 },
  },
}
module.exports = nextConfig

• O que demonstra: override dos dois períodos de invalidação do client cache.

Version History

Versão	Mudança
v15.0.0	Default de dynamic mudou de 30s para 0s.
v14.2.0	staleTimes experimental introduzido.

Key Takeaways

1. O default de dynamic (0s) mudou na v15: código que dependia do comportamento anterior (30s) precisa configurar explicitamente.