Boas Práticas do React 19

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

1. Instale @types/react 19 Juntos: @types/react e @types/react-dom devem ser atualizados na mesma instalação para a linha v19; versões incompatíveis produzem erros de tipo confusos (por exemplo, ref faltando em ComponentProps) que parecem bugs do React.
2. Use o Contexto Diretamente como Provider: <Context.Provider value={…}> está depreciado - renderize <ThemeContext value={theme}>…</ThemeContext> diretamente; a forma antiga .Provider ainda funciona, mas emite um aviso e está destinada à remoção.
3. Apenas Componentes de Servidor Podem Ser async: Marque componentes de carregamento de dados como Componentes de Servidor e use await diretamente no corpo - Componentes de Cliente não podem ser async, não podem usar useState/useEffect e não têm acesso a window, document ou localStorage.
4. Passe Saída do Servidor Através de children: Componentes de Cliente não podem importar Componentes de Servidor (a importação se torna silenciosamente apenas para cliente), então componha passando JSX de Componente de Servidor pré-renderizado através de children ou props JSX nomeadas de um componente pai de Servidor.
5. Serialização Além de JSON: Props que cruzam a fronteira Servidor→Cliente podem ser Date, Map, Set, FormData, arrays tipados, Promises não aguardadas e Server Actions - mas nunca funções regulares, instâncias de classe ou nós DOM.
6. Marque Funções, Não Arquivos: "use server" converte funções async individuais em endpoints RPC, então evite colocá-lo no topo de um arquivo de componente esperando que todas as exportações se tornem actions - isso quebra as exportações do componente em vez disso.
7. Retorne um Objeto de Resultado das Actions: Lançar uma exceção dentro de uma Server Action cruza a fronteira da rede e pode travar o cliente; retorne um resultado discriminado - return { success: true, data } ou return { success: false, error: "Inválido" } - e reserve throw para falhas genuinamente inesperadas capturadas por error.tsx.
8. Observe Cargas Úteis de Closure de Action Inline: Variáveis capturadas por actions "use server" inline são serializadas como campos de formulário ocultos criptografados em cada renderização, então extraia closures pesadas para arquivos de action de nível superior quando o estado capturado ficar grande.
9. Use useFormStatus em um Filho: useFormStatus() reflete apenas o <form> ancestral mais próximo, então chamá-lo no mesmo componente que renderiza o formulário sempre retorna pending: false - mova o botão de leitura de status para um filho do formulário.
10. useActionState Substitui o Estado Inteiramente: O valor de retorno de uma action sobrescreve completamente o estado (sem mesclagem no estilo reducer), então espalhe o estado anterior explicitamente - return { ...prevState, error: "Email inválido" } - e lembre-se de importá-lo de "react", não de "react-dom".
11. Prefira Inputs Não Controlados em Formulários de Action: Inputs controlados perdem valores digitados pelo usuário quando uma action re-renderiza o formulário a partir do estado de erro; inputs não controlados (ou manter valores de input no estado retornado) preservam o input entre erros de validação e os formulários não são redefinidos automaticamente em caso de sucesso.
12. Nunca Crie Promises no Render com use: Criar uma nova promise dentro do corpo do componente e passá-la para use() causa um loop infinito de Suspense; eleve a criação da promise para um Componente de Servidor pai, um cache estável ou uma prop para que a referência seja estável entre as renderizações.
13. Emparelhe use Com Suspense e Error Boundary: use(promise) requer um ancestral Suspense para mostrar o estado de carregamento e um error boundary para capturar rejeições - sem ambos, o aplicativo lança uma exceção ou fica silenciosamente travado em promises pendentes.
14. Chame use Condicionalmente Quando Precisar: Ao contrário dos hooks, use() é legal dentro de if, loops e retornos antecipados - if (shouldLoad) { const data = use(promise) } - aproveite isso para leituras de contexto condicionais e desempacotamento de promises com guarda em vez de forçar formas antigas de useContext/useEffect.
15. Chame addOptimistic Dentro de uma Action: addOptimistic silenciosamente não faz nada a menos que seja invocado dentro de uma action de formulário, um manipulador de Server Action ou uma startTransition explícita; envolva chamadas de manipulador de eventos: startTransition(() => addOptimistic(newItem)) para que a atualização otimista realmente se aplique.
16. Mantenha updateFn Pura: A updateFn passada para useOptimistic deve ser pura e produzir um novo valor - mutar o estado ou referenciar escopo com efeitos colaterais quebra o rollback automático em caso de falha.
17. Exponha Erros Junto com Rollback Otimista: Quando uma action falha e faz rollback, a UI reverte silenciosamente sem indicação; emparelhe useOptimistic com useActionState para que os erros ainda sejam renderizados para o usuário após o rollback.
18. Desestruture ref Antes de Espalhar: Componentes de função agora aceitam ref como uma prop comum, então {...props} acidentalmente encaminha ref junto com todo o resto - desestruture-o explicitamente: ({ ref, ...props }) => <input ref={ref} {...props} />, especialmente quando o componente é um pass-through.
19. Callbacks de Ref Retornam Limpeza: Callbacks de ref agora podem retornar uma função de limpeza (como useEffect); retornar qualquer outra coisa (não função, não undefined) aciona um aviso de desenvolvimento, então retorne uma limpeza ou não retorne nada.
20. Dê Precedência às Folhas de Estilo: <link rel="stylesheet" precedence="…"> opta pela dedupicação, ordenação e Suspense-until-loaded do React - sem precedence, a folha de estilo não é gerenciada e você pode ter FOUC (Flash of Unstyled Content) ou folhas duplicadas.
21. Evite Múltiplas Tags title: React eleva <title> para <head>, mas apenas o último renderizado vence, então espalhar títulos entre componentes produz resultados dependentes da ordem; escolha um único local <title> (ou use a API de metadados do framework) e mantenha-o.
22. preload Baixa, preinit Executa: Use preload quando você só quer os bytes no cache e preinit quando você também quer que scripts sejam executados ou folhas de estilo sejam aplicadas; preinit executa scripts imediatamente e falhará se eles dependerem de DOM que ainda não foi renderizado.
23. Pré-carregue Fontes com crossOrigin Anonymous: A especificação Fetch requer crossOrigin: "anonymous" em pré-carregamentos de fontes, mesmo para requisições same-origin - preload("/font.woff2", { as: "font", crossOrigin: "anonymous" }) - sem isso o navegador baixa a fonte duas vezes e a dica de pré-carregamento é desperdiçada.
24. Siga as Regras do React para o Compilador: O Compilador React ignora silenciosamente qualquer componente que muta props/estado no render ou faz efeitos colaterais durante o render - sem erro de compilação, apenas sem memoização - então trate "renderização pura" como uma regra rígida se você quiser os benefícios do compilador.
25. Execute eslint-plugin-react-compiler: O plugin ESLint sinaliza violações de regras que o compilador ignoraria silenciosamente; combine-o com compilationMode: "annotation" e a diretiva "use memo" para uma implantação gradual, e use "use no memo" para excluir funções específicas.