práticas-recomendadas-react-vercel

Práticas Recomendadas React da Vercel

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 para problemas de desempenho
• Refatorar código React/Next.js existente
• Otimizar tamanho do bundle ou tempos de carregamento

Categorias de Regras por Prioridade

Prioridade	Categoria	Impacto	Prefixo
1	Eliminando Waterfalls	CRÍTICO	async-
2	Otimização do Tamanho do Bundle	CRÍTICO	bundle-
3	Desempenho no Lado do Servidor	ALTO	server-
4	Busca de Dados no Lado do 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. Eliminando Waterfalls (CRÍTICO)

• async-cheap-condition-before-await - Verifique condições síncronas baratas antes de aguardar flags ou valores remotos
• async-defer-await - Mova await para branches onde é realmente usado
• async-parallel - Use Promise.all() para operações independentes
• async-dependencies - Use better-all para dependências parciais
• async-api-routes - Inicie promises cedo, aguarde tarde em rotas de API
• async-suspense-boundaries - Use Suspense para transmitir conteúdo

2. Otimização do Tamanho do Bundle (CRÍTICO)

• bundle-barrel-imports - Importe diretamente, evite arquivos barrel
• bundle-analyzable-paths - Prefira caminhos de importação e sistema de arquivos estaticamente analisáveis para evitar bundles e traces amplos
• bundle-dynamic-imports - Use next/dynamic para componentes pesados
• bundle-defer-third-party - Carregue analytics/logging após a hidratação
• bundle-conditional - Carregue módulos apenas quando a funcionalidade estiver ativada
• bundle-preload - Pré-carregue ao passar o mouse/foco para velocidade percebida

3. Desempenho no Lado do Servidor (ALTO)

• server-auth-actions - Autentique server actions como rotas de API
• server-cache-react - Use React.cache() para desduplicação por requisição
• server-cache-lru - Use cache LRU para cache entre requisições
• server-dedup-props - Evite serialização duplicada em props RSC
• server-hoist-static-io - Eleve I/O estático (fontes, logos) para o nível do módulo
• server-no-shared-module-state - Evite estado de requisição mutável em nível de módulo em RSC/SSR
• server-serialization - Minimize dados passados para componentes cliente
• server-parallel-fetching - Reestruture componentes para paralelizar buscas
• server-parallel-nested-fetching - Encadeie buscas aninhadas por item em Promise.all
• server-after-nonblocking - Use after() para operações não bloqueantes

4. Busca de Dados no Lado do Cliente (MÉDIO-ALTO)

• client-swr-dedup - Use SWR para desduplicação automática de requisições
• client-event-listeners - Desduplique listeners de eventos globais
• client-passive-event-listeners - Use listeners passivos para scroll
• client-localstorage-schema - Version e minimize dados do localStorage

5. Otimização de Re-renderização (MÉDIO)

• rerender-defer-reads - Não se inscreva em estado usado apenas em callbacks
• rerender-memo - Extraia trabalho caro em componentes memoizados
• rerender-memo-with-default-value - Eleve props não primitivas padrão
• rerender-dependencies - Use dependências primitivas em effects
• rerender-derived-state - Inscreva-se em booleanos derivados, não em valores brutos
• rerender-derived-state-no-effect - Derive estado durante a renderização, não em effects
• rerender-functional-setstate - Use setState funcional para callbacks estáveis
• rerender-lazy-state-init - Passe função para useState para valores caros
• rerender-simple-expression-in-memo - Evite memo para primitivos simples
• rerender-split-combined-hooks - Separe hooks com dependências independentes
• rerender-move-effect-to-event - Coloque lógica de interação em event handlers
• rerender-transitions - Use startTransition para atualizações não urgentes
• rerender-use-deferred-value - Adie renderizações caras para manter a entrada responsiva
• rerender-use-ref-transient-values - Use refs para valores transitórios frequentes
• rerender-no-inline-components - Não defina componentes dentro de componentes

6. Desempenho de Renderização (MÉDIO)

• rendering-animate-svg-wrapper - Anime wrapper div, não o elemento SVG
• rendering-content-visibility - Use content-visibility para listas longas
• rendering-hoist-jsx - Extraia JSX estático para fora de componentes
• rendering-svg-precision - Reduza a precisão de coordenadas SVG
• rendering-hydration-no-flicker - Use script inline para dados exclusivos do cliente
• rendering-hydration-suppress-warning - Suprima incompatibilidades esperadas
• rendering-activity - Use o componente Activity para mostrar/esconder
• rendering-conditional-render - Use ternário, não &&, para condicionais
• rendering-usetransition-loading - Prefira useTransition para estado de carregamento
• rendering-resource-hints - Use dicas de recurso do React DOM para pré-carregamento
• rendering-script-defer-async - Use defer ou async em tags script

7. Desempenho JavaScript (BAIXO-MÉDIO)

• js-batch-dom-css - Agrupe mudanças CSS via classes ou cssText
• js-index-maps - Construa Map para buscas repetidas
• js-cache-property-access - Cacheie propriedades de objetos em loops
• js-cache-function-results - Cacheie resultados de funções em Map no nível do módulo
• js-cache-storage - Cacheie leituras de localStorage/sessionStorage
• js-combine-iterations - Combine múltiplos filter/map em um único loop
• js-length-check-first - Verifique o tamanho do array antes de comparação cara
• js-early-exit - Retorne cedo de funções
• js-hoist-regexp - Eleve a criação de RegExp para fora de loops
• js-min-max-loop - Use loop para min/max em vez de sort
• js-set-map-lookups - Use Set/Map para buscas O(1)
• js-tosorted-immutable - Use toSorted() para imutabilidade
• js-flatmap-filter - Use flatMap para mapear e filtrar em uma passada
• js-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 de useEffectEvent em dependências de effect
• advanced-event-handler-refs - Armazene event handlers em refs
• advanced-init-once - Inicialize o app uma vez por carregamento do app
• advanced-use-latest - useLatest para refs de callback estáveis

Como Usar

Leia 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 do porquê é 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