CDN Caching

Core Idea

Next.js define headers Cache-Control padrão que CDNs podem respeitar para cachear na borda, mas variabilidade de resposta baseada em headers customizados (rsc, next-router-state-tree, etc.) torna o cacheamento em CDN não-trivial hoje. A direção futura é cache-key baseado em pathname, eliminando essa dependência.

Key Concepts

• Cache-Control por estratégia de renderização: Static usa s-maxage=31536000; ISR usa s-maxage={revalidate}, stale-while-revalidate={expire-revalidate}; Dynamic usa private, no-cache, no-store, max-age=0, must-revalidate.
• CDN purge separado: revalidateTag()/revalidatePath() só invalida o cache do servidor Next.js, não a CDN; é preciso disparar purge da CDN (HTML e variante RSC) junto.
• _rsc search parameter: hash dos headers relevantes que atua como cache-key, garantindo variantes de resposta corretas mesmo em CDNs que ignoram Vary.
• Headers Vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch, next-url (só em rotas com intercepting routes).
• Header rsc obrigatório: se a CDN remover esse header, o servidor devolve HTML quando o client-side router esperava payload RSC, quebrando navegação client-side.
• Direção futura (pathname-based cache keying): mover tudo que afeta cache pro pathname (/my/page.rsc, /my/page.segments/.../segment.segment.rsc), permitindo dropar search params com segurança e eliminar necessidade de suporte a Vary.

Reference Tables

Tipo de rota	Cache-Control
Static (sem revalidação)	s-maxage=31536000
ISR (revalidação temporal)	s-maxage={revalidate}, stale-while-revalidate={expire-revalidate}
Dynamic	private, no-cache, no-store, max-age=0, must-revalidate
Static assets (/_next/static/)	public, max-age=31536000, immutable

Header	Pode ignorar?	Consequência se ignorado
next-router-state-tree	Sim (não-prefetch)	Servidor retorna payload completo em vez de update segmentado
next-router-segment-prefetch	Sim	Fallback pra prefetch payload mais amplo
next-url	Sim	Intercepting routes não funcionam; usuário vê navegação normal
rsc	Não	Quebra navegação client-side (HTML servido onde RSC era esperado)
next-router-prefetch + _rsc	Não, juntos	_rsc é discriminador obrigatório de cache-busting em prefetch

Anti-patterns

• Deixar CDN dropar query params por padrão: _rsc precisa estar na cache key, senão variantes de resposta (HTML vs RSC) colidem no cache.
• Colocar proxy.js atrás da CDN sem bypass configurado: proxy deve rodar antes do cache da CDN pra continuar sendo fonte de verdade de auth/redirects/rewrites.
• Confiar só em revalidateTag/revalidatePath para atualizar CDN: eles só invalidam o cache do Next.js; sem purge de CDN, a borda continua servindo versão antiga até o s-maxage expirar.
• Desabilitar experimental.validateRSCRequestHeaders sem entender o efeito: por padrão, request RSC com _rsc errado recebe 307 redirect pra hash correto; desabilitar remove essa proteção.

Key Takeaways

1. CDN caching funciona hoje para static/ISR/assets, mas revalidação on-demand exige purge explícito de CDN além do revalidateTag/revalidatePath.
2. O header rsc é o único realmente obrigatório de preservar; os demais degradam graciosamente se ignorados.
3. Prefetches estáticos em rotas com PPR são cacheáveis pela CDN incluindo _rsc na cache key e respeitando Cache-Control.
4. A direção de longo prazo (pathname-based) elimina a necessidade de a CDN entender Vary ou headers customizados.

Connects To

• Deploying to Platforms: tabela completa de compatibilidade de infraestrutura de CDN (edge compute, KV, blob storage, PPR resuming).
• Self-Hosting: alternativa sem CDN de terceiros.
• Streaming / Partial Prerendering: origem dos headers rsc/next-router-* que a CDN precisa lidar.
• assetPrefix: serve assets estáticos de domínio/CDN diferente.