Deploying to Platforms

Core Idea

Explica quais capacidades de infraestrutura cada feature do Next.js exige e como avaliar se uma plataforma de deploy suporta o app corretamente vs. com performance ótima.

Key Concepts

• Functional fidelity: toda feature funciona corretamente; contrato binário validado pelo adapter test suite (passa ou não passa).
• Performance fidelity: features atingem a característica de performance ideal (ex.: shell estático da PPR servido em latência de CDN); é um espectro, difere por plataforma.
• Streaming Required: a plataforma precisa suportar chunked transfer encoding/HTTP2 e não pode bufferizar a resposta antes de enviar ao client.
• Shared Cache Recommended: múltiplas instâncias se beneficiam de cache compartilhado para propagar revalidação/tags entre si; sem isso cada instância mantém cache independente (ainda funcional, mas sem coordenação).
• Edge Stitching: otimização de performance (não requisito de corretude) usada por PPR; toda feature funciona a partir de um único servidor origin.
• Deployment Adapter API: adapterPath em next.config.js; roda em build time, produz output específico da plataforma a partir do build padrão do Next.js; qualquer um pode construir um adapter, sem acesso especial.
• Verified adapter: precisa ser open source E rodar o compatibility test suite completo; listado sob a org GitHub do Next.js.
• cacheHandler: cobre cache de servidor (ISR, route handlers, fetch/unstable_cache com patch, image optimization).
• cacheHandlers (plural): configura backends para o diretivo 'use cache'.

Reference Tables

Feature	Streaming	Shared Cache	Edge Stitching	Notas
Server Components	Required	No	No	Streaming básico
ISR (time-based)	No	Recommended	No	Funciona por instância sem shared cache
ISR (on-demand)	No	Recommended	No	Propagação de tag precisa de shared cache multi-instância
Partial Prerendering	Required	Recommended	Optional	Ver PPR Platform Guide
Cache Components (use cache)	Required	Recommended	No	Shared cache dá consistência cross-instância
Proxy / Middleware	No	No	No	Roda em edge ou origin
Server Actions	Required	No	No	POST com resposta em streaming
after()	No	No	No	Requer suporte a graceful shutdown

CDN	Edge Compute	KV/Tags	Blob Storage	PPR Resuming
Cloudflare	Workers	KV	R2	Sim (worker)
Akamai	EdgeWorkers	EdgeKV	Object Storage	Sim (worker)
Amazon CloudFront	Lambda@Edge	KeyValueStore	S3	Sim (Lambda)
Fastly	Compute	KV Store	Object Storage	Sim (WASM)
Azure	Functions	Managed Redis	Blob Storage	Sim (server)
Google Cloud	Cloud Run	Various KV	Cloud Storage	Sim (server)

Anti-patterns

• Assumir que falta de Edge Stitching quebra a feature: é otimização de performance, não requisito de corretude; tudo funciona de um único origin.
• Tratar building blocks de CDN (KV, blob storage) como integração pronta: a maioria dos community adapters hoje só faz deploy como container Docker/Node.js, sem usar primitivas edge-specific.

Key Takeaways

1. O requisito mínimo absoluto para rodar Next.js é um servidor Node.js; sharp é a única dependência extra obrigatória (Image Optimization).
2. Use o adapter test suite como critério objetivo de "a plataforma suporta Next.js" (functional fidelity), separado de quão rápido ela entrega (performance fidelity).
3. Sem shared cache, ISR/Cache Components ainda funcionam, mas revalidação não se propaga entre instâncias.
4. cacheHandler (singular) e cacheHandlers (plural) cobrem caminhos de cache diferentes: legado/ISR vs. 'use cache'.
5. Adapter aberto + rodando o compatibility suite = "verified adapter"; adapters fechados podem existir mas nunca serão listados como verified.

Connects To

• Debugging (ch038): streaming afeta como erros aparecem no DevTools durante dev vs. produção.
• Draft Mode (ch040): Draft Mode desativa cache de resposta ISR, interagindo com o mesmo modelo de cache discutido aqui.
• Environment Variables (ch041): runtime env vars exigem servidor Node.js compatível com dynamic rendering, o mesmo requisito mínimo desta página.