Boas Práticas Fundamentais do React

20 Fundamentos Básicos Essenciais

Os blocos de construção essenciais que todo aprendiz básico de React deve conhecer antes de mergulhar em padrões avançados.

1. Componentes são funções que retornam JSX: Um componente React é apenas uma função JavaScript/TypeScript que retorna marcação -- o nome da função deve começar com uma letra maiúscula.
2. JSX não é HTML: JSX se parece com HTML, mas compila para JavaScript -- use className em vez de class, htmlFor em vez de for, e camelCase para atributos de evento como onClick.
3. Chaves {} incorporam expressões: Use {variavel} dentro do JSX para exibir valores dinâmicos -- você pode colocar qualquer expressão JavaScript dentro, mas não declarações como if ou for.
4. Props passam dados para baixo: Componentes pais enviam dados para filhos via props -- pense nelas como argumentos de função que fluem em uma direção, de pai para filho.
5. Props são somente leitura: Nunca modifique uma prop diretamente -- se um filho precisar mudar algo, o pai deve passar uma função setter em vez disso.
6. useState adiciona interatividade: Chame useState(valorInicial) para obter um par [valor, setValor] -- atualizar o estado com o setter aciona uma re-renderização.
7. Eventos usam manipuladores camelCase: Anexe manipuladores de eventos como onClick={handleClick} -- passe a referência da função, nunca a chame com parênteses como onClick={handleClick()}.
8. Listas precisam de uma prop key: Ao renderizar arrays com .map(), cada elemento precisa de uma key única para que o React possa rastrear eficientemente adições, remoções e reordenações.
9. Renderização condicional usa ternários ou &&: Mostre ou oculte elementos com {condicao ? <A /> : <B />} ou {condicao && <A />} já que você não pode usar instruções if diretamente dentro do JSX.
10. Inputs controlados pareiam value com onChange: Defina value={estado} e onChange={e => setEstado(e.target.value)} juntos -- definir apenas value torna o input somente leitura.
11. children é uma prop especial: Tudo o que você colocar entre as tags de abertura e fechamento de um componente se torna children -- é assim que você constrói componentes wrapper e de layout.
12. useEffect executa efeitos colaterais: Use useEffect(() => { ... }, [deps]) para coisas que acontecem fora da renderização, como chamadas de API, timers ou assinaturas.
13. O array de dependências controla quando os efeitos são re-executados: Um array vazio [] significa "executar uma vez ao montar" -- listar variáveis significa "re-executar quando estas mudarem" -- omiti-lo significa "executar após cada renderização".
14. import e export conectam arquivos: Use export default ou export para tornar um componente disponível, então import ele em outro arquivo para usá-lo -- o alias @/ aponta para a raiz do seu projeto.
15. Fragments evitam nós extras no DOM: Envolva elementos irmãos em <>...</> (Fragment) quando você não precisa de um <div> extra -- isso mantém sua marcação HTML renderizada limpa.
16. Estilos inline usam objetos JavaScript: Escreva style={{ color: "red", fontSize: "16px" }} com propriedades camelCase -- mas na prática, use um framework CSS como Tailwind em vez disso.
17. Eleve o estado para o pai comum mais próximo: Quando dois componentes irmãos precisam dos mesmos dados, mova o estado para o pai deles e passe-o para baixo como props.
18. Derive valores em vez de sincronizar estado: Se um valor pode ser computado a partir do estado ou props existentes, calcule-o durante a renderização em vez de armazená-lo em um useState separado.
19. TypeScript captura erros antes que cheguem aos usuários: Digite suas props com interface ou type e use arquivos .tsx -- o compilador sinalizará props ausentes, tipos errados e erros de digitação instantaneamente.
20. Mantenha componentes pequenos e focados: Cada componente deve fazer uma coisa bem -- se um componente estiver ficando longo, extraia partes dele em componentes filhos menores.

Top 25 Melhores Práticas Intermediárias

Um resumo condensado das 25 melhores práticas mais importantes extraídas de todas as páginas desta seção.

1. Nunca Defina Componentes Dentro de Componentes: Um componente declarado dentro de outro componente recebe uma nova identidade a cada renderização do pai, então o React o desmonta e remonta a cada vez -- destruindo o estado local e os efeitos; sempre eleve os componentes para o escopo do módulo: function Pai() { function Filho() {} /* ruim - Filho é remontado a cada renderização */ }.
2. Trate Props como Imutáveis: Mutar uma prop (ex: props.itens.push(x)) muta silenciosamente os dados do pai e quebra o modelo de renderização do React; copie para novos arrays ou objetos antes de modificar e deixe o pai ser o dono do estado.
3. Estenda Props Nativas com ComponentPropsWithoutRef: Digite componentes wrapper com React.ComponentPropsWithoutRef<"button"> para que cada atributo nativo permaneça sincronizado com a API DOM; re-declarar props manualmente se torna obsoleto no momento em que a especificação DOM muda.
4. Prefira interface para Props: interface fornece melhores mensagens de erro e suporta a fusão de declarações, então use-a para formas de props de componentes; reserve type para uniões, tipos mapeados e outras transformações que interfaces não podem expressar.
5. Proteja Contra 0 em Condicionais &&: {contagem && <Badge />} renderiza a string literal "0" quando contagem é 0 porque 0 é falsy, mas ainda renderizável; use contagem > 0 && <Badge /> ou um ternário para evitar o infame bug do "0".
6. Unions Discriminadas para Status: Modele o estado como { status: "sucesso"; dados } | { status: "erro"; erro } para que o TypeScript restrinja o tipo dentro de cada branch; isso elimina o ruído do encadeamento opcional e torna as branches inalcançáveis óbvias.
7. Trocar Tipos de Elemento Reseta o Estado: Mudar o tipo de um componente na mesma posição da árvore (ex: <Spinner /> → <DataTable />, ou <input> ↔ <textarea>) desmonta a subárvore antiga e apaga seu estado; mantenha o mesmo tipo e alterne props quando quiser que o estado persista.
8. Passe Manipuladores, Não Invocações: onClick={handleClick} anexa a função; onClick={handleClick()} a chama durante a renderização e usa o valor de retorno como manipulador, o que raramente é o que você quer -- envolva em uma arrow function quando precisar injetar argumentos: onClick={() => handleClick(id)}.
9. onChange Dispara a Cada Tecla: O onChange do React mapeia para o evento nativo input, não para o nativo change, então ele dispara a cada tecla em vez de ao perder o foco -- use onBlur se você realmente quiser a semântica de "confirmar ao perder o foco".
10. Use currentTarget, Não target: e.target é o elemento de onde o evento se originou (que pode ser um filho), enquanto e.currentTarget é o elemento ao qual o manipulador está anexado; leia atributos que você controla de currentTarget para evitar surpresas ao clicar em elementos aninhados.
11. Escape para addEventListener Quando Necessário: Manipuladores de eventos JSX não suportam { passive: false } ou eventos em nível de window/document; para listeners da tecla Escape, monitores de scroll ou touchmove que precisam de preventDefault, use useEffect + addEventListener em um ref e retorne uma limpeza.
12. Inputs Controlados Precisam de value + onChange: Definir value sem um onChange correspondente torna o input somente leitura porque o React fixa o valor do DOM ao estado; pareie os dois -- <input value={nome} onChange={e => setName(e.target.value)} /> -- ou mude para defaultValue para um input não controlado.
13. Checkboxes e Radios Usam checked: Checkboxes e radios consomem checked/defaultChecked, não value/defaultValue; misturá-los silenciosamente faz a coisa errada, já que value em um checkbox é o token submetido, não o estado marcado: <input type="checkbox" checked={ligado} onChange={e => setLigado(e.target.checked)} />.
14. Chame useFormStatus em um Filho: useFormStatus() só retorna informações precisas sobre o status de pendência quando chamado de dentro de um descendente do <form>; chamá-lo no mesmo componente que renderiza o formulário retorna padrões obsoletos sem erro, então extraia o botão de submit para seu próprio componente.
15. Parse Strings de input.value: e.target.value é sempre uma string -- mesmo para <input type="number"> -- então envolva-o com Number(...) ou parseInt(...) antes de usá-lo em cálculos ou para armazenar estado tipado: onChange={e => setIdade(Number(e.target.value))}.
16. Use className, Não class: JSX compila para React.createElement, então o atributo class do HTML é className, for é htmlFor, e estilos recebem um objeto camelCase; usar os nomes HTML compila, mas avisa e pode silenciosamente remover estilos em ambientes rigorosos.
17. Objetos Não São Filhos Válidos: Renderizar {usuario} lança "Objetos não são válidos como filhos React"; renderize um campo específico como {usuario.nome} ou JSON.stringify(usuario) para saída de depuração, e lembre-se que 0 renderiza como texto, mas null/false/undefined não renderizam nada.
18. ReactNode para children, JSX.Element para Retornos: Digite children como React.ReactNode (que cobre JSX, strings, números, arrays, null) e reserve React.JSX.Element para tipos de retorno que sempre retornam um único elemento JSX.
19. Chaves Únicas Entre Irmãos: A key de uma lista deve ser única entre seus irmãos (não globalmente), e deve ser estável entre renderizações -- use item.id, não Math.random() ou Date.now(), ou o React remontará cada linha e destruirá seu estado.
20. Evite Chaves de Índice em Listas Dinâmicas: Usar index como key em listas que reordenam, filtram ou inserem faz com que o React reutilize os nós DOM errados, produzindo valores de input obsoletos e foco quebrado; chaves de índice só são seguras para listas verdadeiramente estáticas.
21. Use key para Forçar Remontagem: Mudar a key em um componente é a maneira canônica de resetar todo o seu estado interno -- <PlayerProfile key={idDoJogadorAtual} /> deliberadamente remonta quando o jogador muda, o que é um recurso, não um hack.
22. Fragments Curtos Não Podem Receber key: O atalho <>...</> não aceita uma prop key; ao mapear fragments, importe Fragment e use <Fragment key={...}>...</Fragment> para evitar avisos de chave duplicada ou renderizações sem chave.
23. ref.current Não Dispara Renderizações: Atualizar ref.current não re-renderiza o componente -- esse é o objetivo; use useRef quando a UI não depende do valor (IDs de timer, observadores, cache de último valor) e useState quando depende.
24. ref É uma Prop Regular no React 19: forwardRef é depreciado; apenas digite ref como uma prop comum com React.Ref<HTMLInputElement> e desestruture-a junto com as outras -- e lembre-se que {...props} agora também espalha ref, então retire-a explicitamente ao passar adiante.
25. Retorne Limpeza de Callbacks de Ref: Callbacks de ref do React 19 podem retornar uma função de limpeza como useEffect, então conecte observadores como ref={node => { if (!node) return; const obs = new ResizeObserver(...); obs.observe(node); return () => obs.disconnect(); }} em vez da antiga dança de verificação de nulo.