Next.js App Router mudou as regras de cache, estado e rendering, e muita equipe levou bug de dado velho para produção antes de entender o novo modelo. As armadilhas abaixo custam dias de debug em projetos reais. Todas passaram por code review antes do incidente.

Por que meus dados aparecem desatualizados?

O cache é agressivo por default: requests de fetch entram no Data Cache e segmentos de rota ficam guardados até você 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, não depois do primeiro ticket.

O que pode atravessar a fronteira entre Server e Client Components?

A fronteira serializa props: funções, classes e instâncias complexas estouram erro em runtime. 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.

Por que minha página carrega tão devagar?

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 para o que pode chegar depois. Um waterfall de três níveis multiplica a latência de rede por três.

Como resolver erros de hidratação?

Objetos Date e valores aleatórios divergem entre render do servidor e do cliente e disparam mismatch warnings. Use serialização determinística: timestamps em ISO string, IDs gerados fora do render, valores formatados com locale fixo. O warning desaparece, e o mistério de produção também.

Route Handlers substituem API Routes?

Handlers do App Router fazem streaming de fábrica, mas acesso a cookies e headers muda de forma em relação ao Pages Router. 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 seu middleware de auth.

Server Actions servem para mutations?

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.

Por que meu bundle cresceu tanto?

Importar biblioteca server-side em Client Component infla 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