Melhores Práticas de Padrões React

Um resumo condensado das 25 melhores práticas mais importantes, extraídas de cada página desta seção.

1. Prefira Slots Nomeados em Vez de um Único children: Sobrecarregar children para layouts multi-região perde o controle de posicionamento; exponha props nomeadas ReactNode - ({ header, sidebar, footer }: { header: ReactNode; sidebar: ReactNode; footer: ReactNode }) - para que os consumidores possam preencher cada slot independentemente e você mantenha o TypeScript do lado deles.
2. Escolha ReactNode, ReactElement ou ComponentType: ReactNode aceita strings/null/arrays (melhor para slots e children), ReactElement restringe a um único elemento JSX, e ComponentType<P> é um componente que você pode instanciar - escolha intencionalmente porque eles tipam diferentes estilos de composição.
3. Construa Componentes Compostos com Base em Contexto: Uma raiz composta possui o estado e o publica via contexto para que Root.Item, Root.Trigger e Root.Content funcionem em qualquer profundidade JSX - proteja o hook consumidor com um erro lançado quando usado fora da raiz em vez de retornar um null silencioso.
4. Marque Raízes Compostas como "use client": Componentes compostos dependem de createContext e useState, então o arquivo raiz deve ser um Client Component no Next.js - e use contexto de dois níveis (AccordionContext + ItemContext por item) para escopar a identidade a cada item.
5. Divida Contextos de Estado e Ações: Coloque o estado em um contexto e as ações memoizadas em outro para que botões que apenas disparam nunca re-renderizem em mudanças de estado; o dispatch do useReducer já é estável no React e não precisa de memoização extra.
6. Nunca Inline Valores de Contexto de Objeto: Passar um literal de objeto recém-criado como value de contexto em cada renderização pai derrota a memoização e re-renderiza todos os consumidores; envolva o valor em useMemo com chave no estado real, ou divida contextos para que consumidores apenas de atualizadores sejam imunes.
7. Escope Provedores Estreitamente: Monte um provedor na menor subárvore que realmente precise dele; um provedor na raiz causa re-renderizações em páginas não relacionadas e torna a divisão de código preguiçosa menos eficaz.
8. Suporte Tanto Controlado Quanto Não Controlado: Componentes de biblioteca devem detectar o modo controlado via value !== undefined e recorrer ao estado interno - const [inner, setInner] = useState(defaultValue); const val = value !== undefined ? value : inner - envolva a decisão em um hook reutilizável useControllableState e nunca mude os modos após a montagem.
9. Não Use Debounce em Atualizações de Estado para Inputs Controlados: Usar debounce no onChange que define o estado congela o input porque o valor do DOM fica atrás do usuário; use debounce para efeitos colaterais (busca, autossalvamento) enquanto sempre atualiza o estado controlado de forma síncrona.
10. Error Boundaries Precisam de getDerivedStateFromError: Implemente getDerivedStateFromError (derivação de estado pura na fase de renderização) para a troca de fallback e componentDidCatch (pós-commit) para logging no Sentry; não há equivalente em hooks, então use uma classe ou react-error-boundary.
11. Resete Boundaries via resetKeys + key: Use resetKeys para que o boundary se recupere automaticamente quando um parâmetro de rota muda, e coloque uma key nos filhos do boundary para que limpar hasError force uma remontagem - simplesmente resetar o estado deixa a subárvore em seu estado corrompido.
12. Saiba o Que Error Boundaries Perdem: Eles não capturam erros em manipuladores de eventos, código assíncrono, SSR ou no próprio boundary; envolva esses em try/catch explícitos, e no Next.js confie na convenção error.tsx no nível da rota com error.digest para erros de servidor.
13. Chame HOCs no Escopo do Módulo: Chamar withAuth(Component) dentro do corpo de outro componente cria um tipo de componente totalmente novo a cada renderização e destrói o estado; aplique HOCs uma vez no escopo do módulo - const ProtectedPage = withAuth(DashboardPage) - e sempre defina um displayName significativo.
14. Encaminhe Refs e Estáticas Através de HOCs: HOCs perdem refs e métodos estáticos por padrão, então envolva com React.forwardRef internamente e copie estáticas com hoist-non-react-statics - caso contrário, os consumidores perdem handles imperativos e constantes anexadas.
15. Profile Antes de Memoizar: memo/useMemo/useCallback prematuros adicionam sobrecarga de comparação que pode tornar componentes rápidos lentos; use o React DevTools Profiler para identificar pontos críticos reais e lembre-se que onClick={() => …} ou style={{…}} inline derrotam o memo por referências novas.
16. useTransition Possui, useDeferredValue Recebe: Use useTransition quando você possui o setter de estado e quer marcar a atualização como não urgente; use useDeferredValue para atrasar um valor que você recebe como prop, e compare-o com o valor atual para mostrar um sutil indicador de obsolescência.
17. Virtualize Listas Grandes: Dezenas de milhares de linhas não podem ser salvas por memo - recorra a react-virtual/react-window ou CSS content-visibility: auto, e mantenha keys estáveis (IDs, não índices) para que as linhas não sejam remontadas ao rolar.
18. createPortal Mantém a Árvore React: Eventos borbulham através da árvore React (não da árvore DOM) através de portais, então cliques dentro de um modal ainda atingem ancestrais React - chame stopPropagation quando precisar de uma quebra limpa, e capture o foco mais salve/restaure-o para modais reais.
19. Proteja Portais para SSR: document.body causa falha na renderização do servidor, então proteja o portal com uma flag mounted definida por useEffect - const [mounted, setMounted] = useState(false); useEffect(() => setMounted(true), []) - ou marque o componente como "use client" no Next.js, e crie um nó container dedicado em vez de acumular divs vazias em body.
20. Cuidado com Render Props Inline: Um children={(state) => <X />} inline cria uma nova referência de função a cada renderização e quebra React.memo no pai; promova a função ou aceite que o memo não se aplicará aqui, e lembre-se que hooks não podem ser chamados dentro de uma função render-prop.
21. Exporte Coleções de Props: Componentes headless devem retornar objetos de props que podem ser espalhados, agrupando manipuladores de eventos mais atributos ARIA - <button {...triggerProps}>Abrir</button> <div {...contentProps}>…</div> - os consumidores não podem esquecer a configuração de acessibilidade porque ela vem com a coleção.
22. Modele o Estado como Uniões Discriminadas: Substitua a sopa de booleanos isLoading/isError/hasData por uma única união marcada status para que combinações impossíveis sejam irrepresentáveis; cada estado carrega apenas os dados válidos para aquele estado.
23. Mantenha Reducers Puros: Sob Strict Mode e renderização concorrente, o React pode chamar um reducer várias vezes, então nunca busque, escreva ou logue dentro dele - e sempre termine com return state para eventos desconhecidos para que transições não tratadas não produzam undefined.
24. Crie Promessas Suspense Fora do Render: Criar uma promessa no corpo do componente dispara um loop infinito de suspensão porque use(promise) trata uma nova referência como uma nova requisição pendente; promova a criação da promessa para um pai, um cache ou um manipulador de eventos.
25. Combine Suspense com Error Boundary e Transition: Uma promessa rejeitada sem um error boundary ancestral desmonta toda a árvore; também use useTransition ao substituir UI impulsionada por Suspense para que fetches rápidos não mostrem um esqueleto, e aninhe boundaries para que conteúdo secundário flua após o shell crítico.