Geruyang/agent-skills-library

Melhores Práticas Next.js

Aplique estas regras ao escrever ou revisar código Next.js.

Convenções de Arquivo

Consulte file-conventions.md para:

• Estrutura de projeto e arquivos especiais
• Segmentos de rota (dinâmicos, catch-all, grupos)
• Rotas paralelas e de interceptação
• Renomeação de middleware na v16 (middleware → proxy)

Limites de RSC

Detecte padrões inválidos de Componentes de Servidor React.

Consulte rsc-boundaries.md para:

• Detecção de componente cliente assíncrono (inválido)
• Detecção de props não serializáveis
• Exceções de Ação do Servidor

Padrões Assíncronos

Alterações na API assíncrona do Next.js 15+.

Consulte async-patterns.md para:

• params e searchParams assíncronos
• cookies() e headers() assíncronos
• Codemod de migração

Seleção de Runtime

Consulte runtime-selection.md para:

• Padrão para runtime Node.js
• Quando o Edge runtime é apropriado

Diretivas

Consulte directives.md para:

• 'use client', 'use server' (React)
• 'use cache' (Next.js)

Funções

Consulte functions.md para:

• Hooks de navegação: useRouter, usePathname, useSearchParams, useParams
• Funções do servidor: cookies, headers, draftMode, after
• Funções de geração: generateStaticParams, generateMetadata

Tratamento de Erros

Consulte error-handling.md para:

• error.tsx, global-error.tsx, not-found.tsx
• redirect, permanentRedirect, notFound
• forbidden, unauthorized (erros de autenticação)
• unstable_rethrow para blocos catch

Padrões de Dados

Consulte data-patterns.md para:

• Componentes de Servidor vs Ações do Servidor vs Manipuladores de Rota
• Evitando waterfalls de dados (Promise.all, Suspense, preload)
• Busca de dados em componente cliente

Manipuladores de Rota

Consulte route-handlers.md para:

• Básico de route.ts
• Conflitos do manipulador GET com page.tsx
• Comportamento do ambiente (sem React DOM)
• Quando usar vs Ações do Servidor

Metadados e Imagens OG

Consulte metadata.md para:

• Metadados estáticos e dinâmicos
• Função generateMetadata
• Geração de imagem OG com next/og
• Convenções de metadados baseadas em arquivo

Otimização de Imagens

Consulte image.md para:

• Sempre use next/image em vez de <img>
• Configuração de imagens remotas
• Atributo sizes responsivo
• Placeholders de desfoque
• Carregamento prioritário para LCP

Otimização de Fontes

Consulte font.md para:

• Configuração de next/font
• Google Fonts, fontes locais
• Integração com Tailwind CSS
• Pré-carregamento de subconjuntos

Empacotamento (Bundling)

Consulte bundling.md para:

• Pacotes incompatíveis com servidor
• Importações CSS (não tags link)
• Polyfills (já incluídos)
• Problemas ESM/CommonJS
• Análise de bundle

Scripts

Consulte scripts.md para:

• next/script vs tags script nativas
• Scripts inline precisam de id
• Estratégias de carregamento
• Google Analytics com @next/third-parties

Erros de Hidratação

Consulte hydration-error.md para:

• Causas comuns (APIs de navegador, datas, HTML inválido)
• Depuração com sobreposição de erro
• Correções para cada causa

Limites de Suspense

Consulte suspense-boundaries.md para:

• Falha de CSR com useSearchParams e usePathname
• Quais hooks exigem limites de Suspense

Rotas Paralelas e de Interceptação

Consulte parallel-routes.md para:

• Padrões de modal com @slot e interceptadores (.)
• default.tsx para fallbacks
• Fechando modais corretamente com router.back()

Auto-hospedagem

Consulte self-hosting.md para:

• output: 'standalone' para Docker
• Manipuladores de cache para ISR multi-instância
• O que funciona vs precisa de configuração extra

Truques de Depuração

Consulte debug-tricks.md para:

• Endpoint MCP para depuração assistida por IA
• Reconstruir rotas específicas com --debug-build-paths