Especialista Next.js no Specsfy: documentação técnica

Quando usar

Acionar quando o projeto depende de next/next.config e a tarefa envolve rota, layout, Server/Client Component, Server Action, route handler, cache, middleware, metadata ou deploy.
Acionar também para diagnosticar waterfalls de dados, hydration mismatch, ou cache servindo dado obsoleto/entre usuários.
Não acionar para hooks, estado ou composição de componentes que não dependem do framework, usar $specsfy-specialist-react nesse caso e voltar aqui só para a fronteira server/client.
Combinar com $specsfy-specialist-application-security quando a rota expõe mutation, upload ou dado sensível, e com $specsfy-specialist-performance-engineering quando o sintoma for Web Vitals ou TTFB fora do SLO.

Confirmar versão do Next.js, router (App ou Pages), runtime (Node vs Edge), deployment target e flags experimentais ativas — a semântica de cache e de Server Components muda entre versões.
Mapear a rota alterada: layout, loading, error, not-found e onde está o boundary entre dado (server) e interação (client).
Manter componentes Server por padrão, marcar "use client" apenas no componente folha que realmente precisa de hook, evento ou API do navegador — nunca no layout ou página inteira por conveniência.
Definir explicitamente cache, revalidação e tags de cada fonte de dado, tratar o comportamento padrão como contrato da versão instalada, não como suposição.
Validar entrada e checar autorização dentro de cada Server Action e route handler, como se fosse um endpoint HTTP público — porque é.
Projetar metadata, streaming (loading.js/Suspense), imagens/fontes e o caminho de recuperação de erro (error.js, not-found.js).
Executar lint, typecheck, testes, build de produção e checar o resultado no runtime real do adapter/host alvo, não só no next dev.

Não mover a árvore inteira para "use client" para “resolver” um erro de hook, isolar a interatividade no componente folha certo.
Nunca importar segredo, cliente de banco ou módulo server-only dentro de um Client Component — o bundler pode incluí-lo no JS enviado ao navegador.
Colocar o fetching o mais próximo possível de quem consome o dado, medir e eliminar waterfalls sequenciais evitáveis (requisições que dependem umas das outras sem necessidade real).
Tratar cache como contrato explícito por rota: declarar se cada fonte de dado é estática, revalidada por tempo, revalidada por tag ou dinâmica — nunca herdar o default sem checar a versão instalada.
Revalidar (revalidatePath/revalidateTag) imediatamente após qualquer mutation que afete dado já cacheado, sem isso a UI mostra estado obsoleto.
Proteger toda Server Action com a mesma disciplina de um endpoint público: autenticar, autorizar por objeto e validar payload — o cliente pode chamá-la diretamente, fora do fluxo de UI esperado.
Usar middleware apenas para lógica curta e compatível com o runtime da rota (Edge tem API restrita), lógica pesada pertence ao route handler ou à camada de aplicação.
Documentar qualquer acoplamento a comportamento específico do host/adapter (headers, streaming, limites de tempo) em vez de deixá-lo implícito.

"use client" no topo de layout.tsx ou page.tsx só porque um filho precisa de interatividade — arrasta toda a subárvore para o cliente e perde os benefícios de Server Components.
Buscar o mesmo dado em múltiplos componentes aninhados sem cache ou deduplicação, criando uma cascata de requisições sequenciais visível no waterfall de rede.
Mutar dado via Server Action e não revalidar o path/tag correspondente — a UI parece “quebrada” porque mostra o cache antigo até o próximo refresh completo.
Confiar em variável de ambiente sem prefixo público (NEXT_PUBLIC_) dentro de um Client Component — ela não existirá no bundle do navegador.
Tratar uma Server Action como “só acessível pela UI” e pular autorização — ela é uma rota HTTP como outra qualquer e pode ser chamada diretamente.

next build completo (mais lint/typecheck do projeto) e leitura do relatório de rotas que ele imprime (estático ○, dinâmico λ, ISR), conferir se isso bate com a intenção declarada no passo 4 do Fluxo.
Exercitar loading, error, not-found, redirects e autorização em cada rota alterada, incluindo acesso direto por URL sem navegação client-side.
Provar cache hit/miss e invalidation: mutar o dado, checar que a rota revalida, e confirmar que nenhum dado vaza entre usuários/sessões diferentes por chave de cache mal escopada.
Medir bundle do cliente, imagens, fontes e Web Vitals (LCP, INP, CLS) antes e depois da mudança quando a rota for sensível a performance.
Não declarar uma rota “seções server-first” ou “cache correto” sem essa evidência, linguagem absoluta sem prova é proibida.

$specsfy-specialist-astro cobre projetos Astro e suas ilhas, não transportar cache ou fronteiras server/client entre os frameworks.
$specsfy-specialist-web-accessibility aprofunda WCAG, foco e tecnologia assistiva nas rotas e Client Components.
$specsfy-specialist-react para hooks, estado, efeitos e composição independentes do framework — use em conjunto para qualquer Client Component não trivial.
$specsfy-specialist-react-ui-components e $specsfy-specialist-ui-design para a biblioteca visual e a composição de página, antes de decidir a fronteira server/client aqui.
$specsfy-specialist-application-security para autorização, upload e dado sensível em Server Actions e route handlers.
$specsfy-specialist-performance-engineering para investigar Web Vitals, TTFB ou regressão de performance com metodologia própria.
$specsfy-specialist-typescript para tipar params de rota, payload de Server Action e retorno de data fetching de forma segura.
$specsfy-specialist-tailwind-css e $specsfy-specialist-shadcn-ui para a camada de estilo e os componentes visuais renderizados dentro de cada Server/Client Component.

Leia references/standards.md para fronteiras server/client, cache, Server Actions, streaming, segurança e checklist de produção, com fontes oficiais.