O App Router reescreveu as regras de cache, estado e rendering. Times levam bug de dado velho para produção antes de entender o novo modelo. Os erros abaixo passaram por code review e custaram dias de debug em projetos reais.

Cache agressivo por default

Requests de fetch entram no Data Cache e segmentos de rota ficam guardados até alguém dizer o contrário. Bugs de stale data rastreiam defaults que ninguém escolheu. force-dynamic, revalidatePath e revalidateTag viram vocabulário diário: aprenda cada um antes do primeiro deploy. A documentação do Next.js descreve Data Cache, Full Cache e Router Cache.

A fronteira serializa props

Funções, classes e instâncias complexas estouram erro em runtime ao cruzar a fronteira Server-Client. Composição com children resolve a maioria dos casos: o Server Component monta a árvore e passa JSX pronto para baixo. Para lógica executável no cliente, injete hooks próprios em vez de tentar atravessar a linha.

Waterfall de requests serializados

await aninhado dentro de Server Components serializa requests em waterfall: o fetch de produto espera o fetch de usuário, que espera a sessão. Promise.all paraleliza o que não depende entre si, e boundaries de Suspense restauram o streaming do que pode chegar depois. Um waterfall de três níveis multiplica a latência de rede por três.

Hidratação determinística

Objetos Date e valores aleatórios divergem entre render do servidor e do cliente e disparam mismatch warnings. Serialize de forma determinística: timestamps em ISO string, IDs gerados fora do render, valores formatados com locale fixo. Os warnings de mismatch param.

Route Handlers: streaming sem API Routes

Handlers do App Router fazem streaming de fábrica. Cookies e headers mudam de forma em relação ao Pages Router: a documentação do Next.js detalha as APIs de request e response. O middleware roda antes de tudo, inclusive assets estáticos, a menos que o matcher exclua esses caminhos. Sem exclusão, cada request de imagem passa pelo middleware de auth.

Server Actions expõem endpoints POST

Server Actions simplificam formulários e expõem endpoints POST mesmo assim. Cheque autenticação e autorização dentro de cada action. Redirecione após a mutation para impedir dupla submissão no refresh. Valide input com zod como faria numa API pública.

Bundle inflado por import errado

Importar biblioteca server-side em Client Component infla o bundle até o build falhar ou a página engasgar. O pacote server-only força a fronteira em tempo de import e transforma esquecimento em erro de build. Rode o analyzer do webpack de vez em quando: drift de bundle entra sem avisar.

O que muda no deploy

  • Self-hosting exige runtime Node para ISR e otimização de imagem
  • Edge runtime restringe bibliotecas: sem fs, sem drivers nativos de banco
  • Recursos específicos de plataforma precisam de adaptadores fora da Vercel