Melhores Práticas Next.js
Regra de Leitura Seletiva
Comece com:
references/senior-master-standard.md
references/usage-routing.md
references/quality-checklist.md
Em seguida, carregue apenas os documentos, scripts, assets ou exemplos herdados que correspondam à tarefa real do usuário.
Princípios para o desenvolvimento com App Router do Next.js.
1. Componentes Servidor vs. Cliente
Árvore de Decisão
Precisa de...?
│
├── useState, useEffect, manipuladores de eventos
│ └── Componente Cliente ('use client')
│
├── Busca de dados direta, sem interatividade
│ └── Componente Servidor (padrão)
│
└── Ambos?
└── Divida: Servidor pai + Cliente filho
Por Padrão
| Tipo | Uso |
|---|
| Servidor | Busca de dados, layout, conteúdo estático |
| Cliente | Formulários, botões, UI interativa |
2. Padrões de Busca de Dados
Estratégia de Fetch
| Padrão | Uso |
|---|
| Padrão | Estático (armazenado em cache no build) |
| Revalidar | ISR (atualização baseada em tempo) |
| Sem cache | Dinâmico (a cada requisição) |
Fluxo de Dados
| Origem | Padrão |
|---|
| Banco de dados | Fetch em Componente Servidor |
| API | fetch com cache |
| Entrada do usuário | Estado do cliente + Server Action |
3. Princípios de Roteamento
Convenções de Arquivo
| Arquivo | Propósito |
|---|
page.tsx | UI da rota |
layout.tsx | Layout compartilhado |
loading.tsx | Estado de carregamento |
error.tsx | Limite de erro |
not-found.tsx | Página 404 |
Organização de Rotas
| Padrão | Uso |
|---|
Grupos de rota (nome) | Organizar sem URL |
Rotas paralelas @slot | Múltiplas páginas no mesmo nível |
Interceptação (.) | Modais overlay |
4. Rotas de API
Manipuladores de Rota
| Método | Uso |
|---|
| GET | Ler dados |
| POST | Criar dados |
| PUT/PATCH | Atualizar dados |
| DELETE | Remover dados |
Melhores Práticas
- Validar entrada com Zod
- Retornar códigos de status adequados
- Tratar erros de forma elegante
- Usar Edge runtime quando possível
5. Princípios de Performance
Otimização de Imagens
- Usar o componente next/image
- Definir prioridade para conteúdo acima da dobra
- Fornecer placeholder de desfoque
- Usar tamanhos responsivos
Otimização de Bundle
- Imports dinâmicos para componentes pesados
- Divisão de código por rota (automática)
- Analisar com bundle analyzer
6. Metadados
Estático vs Dinâmico
| Tipo | Uso |
|---|
| Exportação estática | Metadados fixos |
| generateMetadata | Dinâmico por rota |
Tags Essenciais
- title (50-60 caracteres)
- description (150-160 caracteres)
- Imagens Open Graph
- URL canônica
7. Estratégia de Cache
Camadas de Cache
| Camada | Controle |
|---|
| Requisição | opções do fetch |
| Dados | revalidate/tags |
| Rota completa | configuração da rota |
Revalidação
| Método | Uso |
|---|
| Baseado em tempo | revalidate: 60 |
| Sob demanda | revalidatePath/Tag |
| Sem cache | no-store |
8. Server Actions
Casos de Uso
- Submissões de formulário
- Mutações de dados
- Gatilhos de revalidação
Melhores Práticas
- Marcar com 'use server'
- Validar todas as entradas
- Retornar respostas tipadas
- Tratar erros
9. Anti-Padrões
| ❌ Não faça | ✅ Faça |
|---|
| 'use client' em todo lugar | Servidor por padrão |
| Fetch em componentes cliente | Fetch no servidor |
| Pular estados de carregamento | Use loading.tsx |
| Ignorar limites de erro | Use error.tsx |
| Grandes bundles cliente | Imports dinâmicos |
10. Estrutura do Projeto
app/
├── (marketing)/ # Grupo de rota
│ └── page.tsx
├── (dashboard)/
│ ├── layout.tsx # Layout do dashboard
│ └── page.tsx
├── api/
│ └── [resource]/
│ └── route.ts
└── components/
└── ui/
Lembre-se: Componentes Servidor são o padrão por um motivo. Comece por eles, adicione cliente apenas quando necessário.
Quando Usar
Este skill é aplicável para executar o fluxo de trabalho ou ações descritas na visão geral.
Limitações
- Use este skill apenas quando a tarefa corresponder claramente ao escopo descrito acima.
- Não trate a saída como substituta para validação, teste ou revisão específica do ambiente.
- Pare e peça esclarecimentos se entradas necessárias, permissões, limites de segurança ou critérios de sucesso estiverem faltando.