Engenheiro Sênior Next.js / React / TypeScript
O Next.js muda rapidamente e a memória do modelo frequentemente está desatualizada. Antes de usar qualquer API que dependa de uma versão, verifique references/versions.md. Se o next instalado tiver documentação empacotada (node_modules/next/dist/docs/) ou um AGENTS.md gerado pelo Next.js, prefira esses em vez da memória.
Etapa 0: detectar versões e convenções (sempre)
Execute bash scripts/detect_versions.sh (somente leitura), depois confirme:
-
package.json+ lockfile (pnpm/npm/yarn/bun) → next, react, typescript, tailwindcss, ferramentas de teste; use o gerenciador de pacotes do lockfile -
next.config.*→cacheComponents,partialPrefetching,reactCompiler,experimental.* - Roteador:
app/vssrc/app/, quaisquerpages/(roteadores mistos),proxy.tsvsmiddleware.tslegado - Camada de dados: ORM/SDK, módulos
lib/dal.tsouserver-onlyexistentes, biblioteca de autenticação - Estilização e kit de UI (versão do Tailwind, CSS Modules, shadcn/ui, tokens de design), lint/format (ESLint flat config vs Biome)
- Testes: Vitest/Jest, Testing Library, Playwright; scripts de CI existentes
Corresponda às convenções existentes. Se o projeto estiver em uma versão anterior, escreva código que funcione nessa versão.
Padrões (um por decisão, com saída de emergência)
| Decisão | Padrão | Use a alternativa quando |
|---|---|---|
| Tipo de componente | Server Component | Precisar de estado, efeitos, APIs do navegador ou manipuladores de eventos → "use client" na menor folha |
| Modelo de cache (16.x) | Cache Components (cacheComponents: true, 'use cache' + cacheLife/cacheTag) | Aplicativo existente no modelo anterior sem migração planejada. Não faça meia migração |
| Mutações | Server Actions + revalidateTag/updateTag/refresh | API pública consumida por outros clientes → route handler |
| Acesso a dados | Uma camada de acesso a dados (DAL) somente para servidor que autentica e autoriza cada leitura/escrita | — |
| Interceptação de requisições | proxy.ts apenas para redirecionamentos/reescritas/cabeçalhos | Nunca para autorização como única verificação |
| Runtime | Node.js (padrão) | Nenhum em 16.3+: runtime = 'edge' está obsoleto/não suportado |
| Formulários | <form action={serverAction}> + useActionState + validação de esquema (zod ou do projeto) no servidor | Assistentes complexos apenas no cliente → biblioteca de formulário cliente já existente no projeto |
| Estilização | Sistema do projeto; para novos projetos Tailwind CSS v4 com configuração CSS-first | — |
| Estado do cliente | Parâmetros de busca da URL → estado do servidor → estado do React; estado global apenas se comprovadamente necessário | — |
| Memorização | React Compiler se ativado; caso contrário, memorize apenas pontos críticos medidos | — |
| Testes | Vitest + Testing Library para unidades; Playwright para fluxos críticos de E2E | Jest já configurado |
Fluxo de trabalho A: construir uma rota ou funcionalidade
- [ ] Etapa 0 concluída
- [ ] Segmento de rota: page.tsx, layout.tsx, loading.tsx/limites Suspense, error.tsx, not-found.tsx conforme necessário
- [ ] Dados via DAL (somente servidor), aguardados em Server Components; params/searchParams são Promises: `const { id } = await params`
- [ ] Decida o que é armazenado em cache ('use cache' + cacheLife/cacheTag) vs tempo de requisição (dentro de Suspense)
- [ ] Mutações via Server Actions: valide a entrada, re-verifique a autorização na ação, revalide tags
- [ ] Componentes clientes mínimos; props serializáveis; nenhum segredo em pacotes do cliente (apenas NEXT_PUBLIC_* chegam ao navegador)
- [ ] Acessibilidade: elementos semânticos, rótulos, gerenciamento de foco, caminhos de teclado, contraste de cores
- [ ] Testes para lógica + um E2E para o caminho crítico
- [ ] Loop de validação passa
Validar → corrigir → repetir:
pnpm exec tsc --noEmit # ou equivalentes npm/yarn/bun
pnpm lint # ESLint ou Biome por projeto (next lint foi removido no 16)
pnpm test -- --run # Vitest
pnpm build # captura erros de Cache Components / pré-renderização
pnpm exec playwright test # quando E2E existir
Erros de next build sobre dados não armazenados em cache fora de <Suspense> são sinais, não ruído. Corrija adicionando 'use cache', movendo o acesso para dentro de um limite Suspense, ou marcando-o como tempo de requisição.
Fluxo de trabalho B: atualizar Next.js (baixa liberdade)
- [ ] Leia "Padrões antigos" e pisos de segurança em references/versions.md
- [ ] Commit de uma árvore limpa; crie um branch
- [ ] Execute a ferramenta oficial de upgrade: `npx next@canary upgrade --agent=latest`
(ou `npx @next/codemod@canary upgrade latest` se o fluxo do agente não estiver disponível)
- [ ] Atualize react, react-dom e @types/react junto com next
- [ ] Remova exportações `runtime = 'edge'`; renomeie middleware.ts → proxy.ts (runtime Node)
- [ ] Loop de validação; depois teste manualmente autenticação, redirecionamentos, cache e revalidação
Segurança primeiro: se a versão instalada estiver abaixo de um piso corrigido em versions.md, atualize o próprio next (corrigir apenas os pacotes React não é suficiente).
Fluxo de trabalho C: adotar Cache Components em um aplicativo existente
Migre rota por rota. Ative cacheComponents (+ partialPrefetching no 16.4+) em um branch, execute next build e corrija cada limite reportado. Veja references/caching.md. Se instalada, a habilidade next-cache-components-adoption do Next.js cobre os mecanismos em detalhes; use-a junto com esta.
Regras de autenticação e segurança
- Autorize na DAL e em cada Server Action e route handler. Verificações de proxy/middleware são apenas um redirecionamento otimista. CVE-2025-29927 mostrou que bypass baseado em cabeçalho do middleware é possível.
- Server Actions são endpoints HTTP públicos: valide a entrada, verifique a sessão, verifique a propriedade.
- Importe
server-onlyem módulos com segredos ou acesso a banco de dados; retorne DTOs (apenas campos necessários) para Client Components. - Detalhes:
references/data-and-auth.md.
Implementando a partir de um design ou mockup
- Inventarie o design: tokens (cor, escala de tipo, espaçamento, raio), componentes, estados (hover, focus, disabled, loading, empty, error) e breakpoints.
- Mapeie-os primeiro para os tokens e componentes existentes do projeto; adicione novos tokens ao tema, não como valores avulsos.
- Construa a marcação estática do Server Component primeiro, depois adicione interatividade nas folhas.
- Verifique em 320px, larguras de tablet e desktop. Verifique o teclado e os rótulos do leitor de tela. Respeite
prefers-reduced-motion. - Se uma ferramenta de navegador ou Playwright estiver disponível, tire um screenshot e compare com o mockup; itere até que o espaçamento e a tipografia correspondam.
Modo de revisão
Use references/review-checklist.md. Relate cada descoberta como bloqueador / deve-corrigir / detalhe, com arquivo:linha, o problema e uma correção de código concreta. Ordene as descobertas por gravidade. Bloqueadores incluem: autenticação apenas no proxy, segredos chegando a pacotes do cliente, entrada de Server Action não validada, uma versão vulnerável do next e dados específicos do usuário dentro de um escopo 'use cache' compartilhado.
Mapa de referência
references/versions.md: versões, pisos de segurança, padrões antigos, notas de verificaçãoreferences/data-and-auth.md: padrão DAL, template de Server Action, gerenciamento de sessãoreferences/caching.md: regras de Cache Components, ensureStatic, navigation()/prefetch()references/review-checklist.md: regras classificadas por impacto