Práticas Recomendadas do Vercel para React
Guia abrangente de otimização de desempenho para aplicações React e Next.js, mantido pela Vercel. Contém 70 regras em 8 categorias, priorizadas por impacto para orientar refatoração automatizada e geração de código.
Quando Aplicar
Consulte estas diretrizes ao:
- Escrever novos componentes React ou páginas Next.js
- Implementar busca de dados (cliente ou servidor)
- Revisar código em busca de problemas de desempenho
- Refatorar código React/Next.js existente
- Otimizar tamanho do bundle ou tempo de carregamento
Categorias de Regras por Prioridade
| Prioridade | Categoria | Impacto | Prefixo |
|---|---|---|---|
| 1 | Eliminação de Waterfalls | CRÍTICO | async- |
| 2 | Otimização do Tamanho do Bundle | CRÍTICO | bundle- |
| 3 | Desempenho no Servidor | ALTO | server- |
| 4 | Busca de Dados no Cliente | MÉDIO-ALTO | client- |
| 5 | Otimização de Re-renderização | MÉDIO | rerender- |
| 6 | Desempenho de Renderização | MÉDIO | rendering- |
| 7 | Desempenho JavaScript | BAIXO-MÉDIO | js- |
| 8 | Padrões Avançados | BAIXO | advanced- |
Referência Rápida
1. Eliminação de Waterfalls (CRÍTICO)
async-cheap-condition-before-await- Verifique condições síncronas baratas antes de aguardar flags ou valores remotosasync-defer-await- Mova o await para os ramos onde é realmente usadoasync-parallel- Use Promise.all() para operações independentesasync-dependencies- Use better-all para dependências parciaisasync-api-routes- Inicie promises cedo, aguarde tarde em rotas de APIasync-suspense-boundaries- Use Suspense para fazer streaming de conteúdo
2. Otimização do Tamanho do Bundle (CRÍTICO)
bundle-barrel-imports- Importe diretamente, evite arquivos barrelbundle-analyzable-paths- Prefira caminhos de importação e sistema de arquivos estaticamente analisáveis para evitar bundles e rastreamentos amplosbundle-dynamic-imports- Use next/dynamic para componentes pesadosbundle-defer-third-party- Carregue análises/logging após a hidrataçãobundle-conditional- Carregue módulos apenas quando a funcionalidade estiver ativadabundle-preload- Pré-carregue ao passar o mouse/foco para velocidade percebida
3. Desempenho no Servidor (ALTO)
server-auth-actions- Autentique ações do servidor como rotas de APIserver-cache-react- Use React.cache() para desduplicação por requisiçãoserver-cache-lru- Use cache LRU para cache entre requisiçõesserver-dedup-props- Evite serialização duplicada nas props do RSCserver-hoist-static-io- Eleve I/O estático (fontes, logotipos) ao nível do móduloserver-no-shared-module-state- Evite estado mutável no nível do módulo em requisições RSC/SSRserver-serialization- Minimize dados passados para componentes clienteserver-parallel-fetching- Reestruture componentes para paralelizar buscasserver-parallel-nested-fetching- Encadeie buscas aninhadas por item em Promise.allserver-after-nonblocking- Use after() para operações não bloqueantes
4. Busca de Dados no Cliente (MÉDIO-ALTO)
client-swr-dedup- Use SWR para desduplicação automática de requisiçõesclient-event-listeners- Desduplique listeners de eventos globaisclient-passive-event-listeners- Use listeners passivos para rolagemclient-localstorage-schema- Versione e minimize dados do localStorage
5. Otimização de Re-renderização (MÉDIO)
rerender-defer-reads- Não inscreva-se em estado usado apenas em callbacksrerender-memo- Extraia trabalho caro em componentes memoizadosrerender-memo-with-default-value- Eleve props não primitivas padrãorerender-dependencies- Use dependências primitivas em effectsrerender-derived-state- Inscreva-se em booleanos derivados, não valores brutosrerender-derived-state-no-effect- Derive estado durante a renderização, não em effectsrerender-functional-setstate- Use setState funcional para callbacks estáveisrerender-lazy-state-init- Passe função para useState para valores carosrerender-simple-expression-in-memo- Evite memo para primitivos simplesrerender-split-combined-hooks- Divida hooks com dependências independentesrerender-move-effect-to-event- Coloque lógica de interação em manipuladores de eventosrerender-transitions- Use startTransition para atualizações não urgentesrerender-use-deferred-value- Adie renderizações caras para manter a entrada responsivarerender-use-ref-transient-values- Use refs para valores transitórios frequentesrerender-no-inline-components- Não defina componentes dentro de componentes
6. Desempenho de Renderização (MÉDIO)
rendering-animate-svg-wrapper- Anime o wrapper div, não o elemento SVGrendering-content-visibility- Use content-visibility para listas longasrendering-hoist-jsx- Extraia JSX estático para fora dos componentesrendering-svg-precision- Reduza a precisão das coordenadas SVGrendering-hydration-no-flicker- Use script inline para dados apenas do clienterendering-hydration-suppress-warning- Suprima incompatibilidades esperadasrendering-activity- Use o componente Activity para mostrar/esconderrendering-conditional-render- Use ternário, não && para condicionaisrendering-usetransition-loading- Prefira useTransition para estado de carregamentorendering-resource-hints- Use dicas de recurso do React DOM para pré-carregamentorendering-script-defer-async- Use defer ou async em tags script
7. Desempenho JavaScript (BAIXO-MÉDIO)
js-batch-dom-css- Agrupe alterações CSS via classes ou cssTextjs-index-maps- Construa Map para buscas repetidasjs-cache-property-access- Armazene em cache propriedades de objetos em loopsjs-cache-function-results- Armazene em cache resultados de funções em Map no nível do módulojs-cache-storage- Armazene em cache leituras de localStorage/sessionStoragejs-combine-iterations- Combine múltiplos filter/map em um único loopjs-length-check-first- Verifique o comprimento do array antes de comparações carasjs-early-exit- Retorne cedo de funçõesjs-hoist-regexp- Eleve a criação de RegExp para fora dos loopsjs-min-max-loop- Use loop para min/max em vez de sortjs-set-map-lookups- Use Set/Map para buscas O(1)js-tosorted-immutable- Use toSorted() para imutabilidadejs-flatmap-filter- Use flatMap para mapear e filtrar em uma passadajs-request-idle-callback- Adie trabalho não crítico para o tempo ocioso do navegador
8. Padrões Avançados (BAIXO)
advanced-effect-event-deps- Não coloque resultados deuseEffectEventnas dependências do effectadvanced-event-handler-refs- Armazene manipuladores de eventos em refsadvanced-init-once- Inicialize o aplicativo uma vez por carregamentoadvanced-use-latest- useLatest para refs de callback estáveis
Como Usar
Leia os arquivos de regra individuais para explicações detalhadas e exemplos de código:
rules/async-parallel.md
rules/bundle-barrel-imports.md
Cada arquivo de regra contém:
- Breve explicação de por que é importante
- Exemplo de código incorreto com explicação
- Exemplo de código correto com explicação
- Contexto adicional e referências
Documento Compilado Completo
Para o guia completo com todas as regras expandidas: AGENTS.md