Melhores Práticas de Configuração do Next.js

Um resumo condensado das 25 melhores práticas mais importantes extraídas de cada página desta seção.

1. Gere um AUTH_SECRET Real: O Auth.js requer um AUTH_SECRET de 32+ caracteres; use npx auth secret para obter um valor criptograficamente forte e dê segredos diferentes para desenvolvimento e produção, para que uma chave de desenvolvimento vazada não comprometa sessões reais.
2. Separe auth.config de auth.ts: Mantenha um auth.config.ts seguro para edge (sem adaptadores, sem drivers de banco de dados) separado de auth.ts, onde você configura o adaptador de banco de dados, para que o middleware possa chamar auth() sob o Edge Runtime sem importar código exclusivo para Node.
3. Aumente o Tipo de Sessão: Declare claims personalizados em Session e JWT em types/next-auth.d.ts via aumento de módulo para que session.user.role, subscriptionStatus, etc. sejam tipados em todos os Server Components, actions e middleware.
4. Fixe create-next-app para Reprodutibilidade: Os padrões da CLI mudam entre as versões e o modo interativo reutiliza silenciosamente preferências em cache, então fixe create-next-app@15 (ou qualquer versão principal que você queira) e passe --reset-preferences ou flags explícitas em CI para que os scaffolds sejam determinísticos.
5. Cache fetch Explicitamente no Next 15: O padrão no Next.js 15+ é cache: "auto", não force-cache, então defina cache ou next: { revalidate: N } em cada fetch em vez de assumir que os dados estão em cache - o fetching silencioso por solicitação é uma regressão comum do Next 14.
6. Copie static e public para standalone: output: "standalone" produz um servidor minúsculo autônomo, mas exclui .next/static e public/ - seu Dockerfile ou script de deploy deve copiar ambos, caso contrário, o aplicativo servirá 404s para os assets.
7. Defina HOSTNAME=0.0.0.0 em Contêineres: O servidor standalone se vincula a 127.0.0.1 por padrão, então dentro de um contêiner Fargate/EKS/Docker você deve definir ENV HOSTNAME=0.0.0.0 (e uma PORT explícita) ou o health check do load balancer nunca alcançará o aplicativo.
8. Use um Cache Handler ISR Compartilhado: Os dados ISR são cacheados por contêiner por padrão, então implantações multi-contêiner mostram versões inconsistentes até que você configure um cacheHandler baseado em Redis em next.config com cacheMaxMemorySize: 0.
9. Prefira pm2 reload em Vez de restart: No EC2, pm2 reload faz uma reinicialização gradual e elegante entre os workers do cluster para deploys sem downtime; pm2 restart mata todos os workers e produz uma janela de indisponibilidade visível.
10. Deixe o Nginx Servir _next/static: Configure o Nginx para servir /_next/static/ e public/ diretamente com Cache-Control: public, immutable, max-age=31536000 para que os assets estáticos ignorem o Node completamente e sobrevivam às reinicializações do aplicativo.
11. Preserve .next/cache Entre Deploys: Scripts de deploy devem deletar .next/server/ e .next/static/, mas manter .next/cache/ para que os caches ISR e de build sobrevivam; um rm -rf .next bruto os apaga e força reconstruções completas mais regeneração ISR a frio.
12. Use um Cliente Prisma Singleton: Anexe o cliente a globalThis em desenvolvimento para que o hot-reload não abra um novo pool de conexões a cada salvamento - sem isso, o Postgres recusa novas conexões em minutos e o servidor de desenvolvimento trava.
13. Coloque DATABASE_URL em .env: A CLI do Prisma lê .env, não .env.local, então prisma generate e migrate falham silenciosamente ou com mensagens confusas se a URL estiver apenas em .env.local.
14. revalidatePath Após Mutações: Server Actions que escrevem dados devem chamar revalidatePath (ou revalidateTag) depois, caso contrário, a renderização do Server Component em cache continuará servindo dados desatualizados e a UI parecerá não atualizar.
15. Use prisma migrate deploy em CI: Pipelines de CI devem executar prisma migrate deploy (não interativo, aplica migrações commitadas); prisma migrate dev é interativo, pode resetar o banco de dados e nunca deve ser executado contra produção ou staging.
16. Valide Frontmatter MDX Com Zod: gray-matter retorna quaisquer chaves que estejam no arquivo, então passe o resultado por um schema Zod para capturar erros de digitação e campos obrigatórios ausentes no momento da importação, em vez de enviar documentação quebrada.
17. Escape Chaves e JSX em Prosa MDX: Chaves avaliam como JavaScript e <Tag /> são parseadas como JSX, então envolva exemplos de código em backticks ou escape as chaves - caso contrário, o MDX lançará erros de build em prosa que parece normal em Markdown simples.
18. Crie Clientes Stripe no Cadastro: Crie o cliente Stripe em events.createUser do Auth.js, não durante o checkout, para que não haja uma corrida de duplo clique que produza clientes duplicados e o usuário tenha um ID Stripe no momento em que existir.
19. Verifique Webhooks Stripe Com constructEvent: Um manipulador de webhook Stripe deve ler o corpo bruto e chamar stripe.webhooks.constructEvent(rawBody, sig, whsec); parsear JSON sem verificar a assinatura permite que qualquer pessoa mutate seu banco de dados via POSTs forjados.
20. Force o Runtime nodejs para Webhooks: Defina export const runtime = "nodejs" na rota do webhook Stripe porque crypto.createHmac não está disponível no Edge Runtime, e use um STRIPE_WEBHOOK_SECRET distinto por ambiente ou as assinaturas falharão silenciosamente.
21. Configuração do Tailwind v4 Vive no CSS: O Tailwind v4 não tem tailwind.config.js - tokens de tema, variantes e plugins são declarados em globals.css via @theme e @custom-variant, e o plugin PostCSS é @tailwindcss/postcss, não o antigo pacote tailwindcss.
22. Sempre Componha Classes Com cn(): Componentes shadcn colapsam utilitários conflitantes via cn() (clsx + tailwind-merge), então concatene classes através de cn(...) em vez de template strings - caso contrário, as substituições de props do consumidor perderão aleatoriamente para os padrões.
23. Declare Variáveis de Ambiente em turbo.json: O Turborepo remove qualquer variável de ambiente que não esteja listada no array env da tarefa, então variáveis não listadas são undefined no momento da build; declare explicitamente cada variável de ambiente de build ou as chaves de cache não refletirão sua configuração.
24. transpilePackages para UI do Workspace: O Next.js não compila TSX bruto de node_modules, então ao consumir pacotes internos do monorepo como @repo/ui adicione-os a transpilePackages em next.config.ts ou as importações darão erro na build.
25. Use workspace: Com pnpm:* O protocolo workspace:* é entendido apenas por pnpm, yarn e bun - npm não o parseia; defina "packageManager": "pnpm@…" no package.json raiz e use --frozen-lockfile em CI para evitar desvios.