CS Fundamentals Trainer · Guias

React avançado: re-renderizações, memoização, refs, busca de dados e o que o React 19 mudou

Como o React renderiza e re-renderiza, uma escada de triagem que vai de medir, passando por estrutura, cache e o React Compiler, até transições e virtualização, identidade e chaves, Context contra contextos divididos e stores, closures obsoletas, refs, layout e portais, busca de dados (cascatas e respostas fora de ordem explicadas por aritmética que você pode conferir, e como medir o seu app) e tratamento de erros, com o que o React 19.3 mudou.

70 min de leitura

A maior parte dos problemas de React não está na sintaxe. Está em quando os componentes rodam, no que eles lembram entre execuções e em qual versão dos seus dados um trecho de código está enxergando. Este guia se organiza em torno disso. Ele começa com uma escada de triagem (a correção mais barata e segura primeiro) e um índice de sintomas, e depois explica o mecanismo por trás de cada degrau: renderização, estrutura, memoização e o React Compiler, urgência e fazer menos, identidade e chaves, estado compartilhado, efeitos e valores obsoletos, refs, layout e portais, dados assíncronos e tratamento de erros. Ele também marca o que mudou no React 19, porque várias receitas antigas agora são diferentes.

Como ler.

Você querLeia
O modelo e as correções em 15 minutosComece aqui, as seções 1 e 2, o Resumo rápido
Consertar uma tela lenta ou erradaComece aqui, depois o índice de sintomas, depois a seção que ele indica
O quadro completoEm ordem. As seções 3 (verificações do compilador), 7 (closures), 10 (dados) e 11 (erros) são os aprofundamentos; pule-as na primeira leitura

Sobre os exemplos. Os trechos de React são ilustrativos e seguem a documentação do React 19.3, a versão mais recente no momento da escrita (9 de setembro de 2026). Os quatro scripts do apêndice são JavaScript puro em Node.js 22 que modelam mecanismos por trás das seções 7 e 10; não são React.

Que tipo de evidência há neste guia.

TipoOndeQuanto confiar
Comportamento documentadoreact.dev, MDN, TanStack e as outras fontes citadas no textotanto quanto a fonte; confira a versão
Raciocínio derivadoa comparação de Context (seção 6) e a probabilidade de corrida (seção 10)decorre das regras enunciadas; confirme no seu próprio Profiler ou painel de rede
Demonstração de mecanismoos scripts do apêndicemostram por que um padrão se comporta assim; os números dependem de parâmetros escolhidos pelo autor
Medido em um app realnenhumnenhum número deste guia descreve o seu app ou a produção; a seção 4 mostra como registrar o seu

Comece aqui: uma escada de triagem

Em resumo. Meça primeiro, depois escolha a correção mais barata que remove a causa. Cada degrau custa mais complexidade que o de cima, então pare assim que o problema sumir.

DegrauPergunteCorreção típicaO que ela custaSeção
1. MedirEstá lento para uma pessoa, e em qual interação?grave uma interação fixa no Profiler; olhe o painel Performancenada4
2. Remover trabalho pela estruturaAlgo re-renderiza sem depender do que mudou?mover o estado para baixo; subir o conteúdo como childrenuma pequena refatoração, fácil de desfazer2
3. Guardar em cacheUm componente caro re-renderiza com entradas iguais?o React Compiler; senão memo e useMemoa estabilidade das props vira sua tarefa; bugs de cache obsoleto3
4. ReordenarO trabalho é necessário, mas não urgente?useTransition, useDeferredValuea tela fica brevemente desatualizada; o trabalho total não diminui4
5. Fazer menosSimplesmente há coisa demais para renderizar?virtualização, paginação, content-visibilitybusca na página, foco, acessibilidade e posição de rolagem exigem cuidado4
6. MoverÉ computação, não renderização?um Web Worker, ou o servidorserialização e uma arquitetura mais complexa4

A ordem é por risco, não por poder. Mudanças de estrutura não ficam obsoletas e são fáceis de ler; o cache pode servir dados antigos em silêncio; a virtualização muda o comportamento da página para teclado, leitores de tela e busca. Uma equipe que pula para o degrau 5 diante de um problema que o degrau 2 resolve paga por isso durante anos.

Índice de sintomas.

O que você vêCausa habitualPrimeira correçãoSeção
Digitar em um campo travao estado está alto demais, acima de uma árvore lentamover o estado para baixo, ou subir o conteúdo lento2, 4
Uma lista fica lenta a cada mudançaas linhas re-renderizam com dados iguaiscompilador ou memo com props estáveis; virtualizar se houver muitíssimas linhas3, 4
Um formulário perde o texto ou o foco quando algo atualizaum componente definido dentro de outro, ou uma key instáveldeclare-o no nível superior; use chaves estáveis5
Depois de reordenar, uma linha fica com o campo de outraíndice do array usado como keyuse o id do registro5
Uma mudança de contexto re-renderiza metade da páginatodo consumidor acompanha toda mudançadivida o contexto, ou use um store com seletores6
Um timer ou manipulador registra um valor antigoclosure obsoletaliste a dependência, use um atualizador ou useEffectEvent7
A tela mostra dados de outro item após cliques rápidosuma resposta mais lenta e mais antiga chegou por últimolimpeza com flag de ignorar, ou uma biblioteca de dados10
A página se preenche passo a passouma cascata de requisiçõeseleve, faça prefetch ou reestruture as requisições10
A tela inteira fica em branco após um erronão há error boundaryboundaries no nível da página e do widget11
Um modal ou tooltip aparece cortadoum ancestral com overflow ou um contexto de empilhamentoum portal, ou o <dialog> nativo9
Uma posição pisca depois de medirmedição em useEffectuseLayoutEffect, ou CSS9

1. Como o React renderiza

Em resumo. Uma renderização é o React chamando a sua função, não uma atualização da tela. Por padrão os pais re-renderizam os filhos; as props não são o gatilho.

Três palavras são usadas de forma solta e precisam ser exatas.

O React trabalha em duas fases. Na fase de renderização, ele chama os componentes para calcular como a interface deve ficar e compara isso com o resultado anterior. Na fase de commit, ele aplica as diferenças ao DOM, atualiza as refs e executa os efeitos de layout; os efeitos comuns (useEffect) rodam depois. Assim, um componente pode renderizar sem causar nenhuma mudança no DOM e, na renderização concorrente, a fase de renderização pode ser pausada, repetida ou descartada, e é por isso que a renderização deve ser pura: sem mutar objetos existentes, sem requisições de rede, sem Math.random() ou Date.now() no resultado, sem atualizações de estado durante a renderização (Erikson, documentação do React).

Uma renderização é disparada por uma atualização de estado (no próprio componente ou em um hook que ele chama, mesmo que o valor nunca seja exibido), por uma mudança em um contexto que ele lê, ou pela renderização do seu pai. A última é a surpresa: por padrão, quando um componente renderiza, o React renderiza todos os filhos que ele devolve, tenham as props mudado ou não, e assim por diante pela árvore abaixo. Pular um componente pula toda a sua subárvore (Erikson). A mudança de props não é o que dispara uma re-renderização; ela só importa quando você pede ao React que as compare (seção 3).

Diagram: What happens after a state update

Um modelo padrão, não uma lei. "Um pai re-renderiza os seus filhos" descreve o que acontece a menos que algo o impeça, e várias coisas podem impedir: o elemento do filho é o mesmo objeto da vez anterior porque foi criado mais acima (seção 2), o filho está envolvido em React.memo e as suas props são shallow-equal (seção 3), ou o React Compiler memoizou o elemento (seção 3). Assim, o conjunto de componentes que realmente rodam depois de uma atualização de estado costuma ser menor do que a subárvore abaixo do componente que mudou, e ele se move quando você adiciona memoização ou liga o compilador. Não raciocine só a partir da regra: abra o Profiler do React DevTools e veja quais componentes renderizaram e por quê.

Duas consequências práticas. Uma re-renderização não é um bug: é assim que o React mostra dados novos, e para a maioria dos componentes custa microssegundos. Ela importa quando um componente lento re-renderiza com muita frequência, por exemplo uma árvore grande abaixo de um campo que atualiza a cada tecla. E em desenvolvimento, o Strict Mode renderiza os componentes duas vezes para expor código impuro; portanto, um console.log no corpo de um componente que aparece duas vezes é esperado.

2. Manter as re-renderizações pequenas pela estrutura

Em resumo. Mova o estado para baixo, ou passe a parte lenta como children. Isso remove trabalho em vez de guardá-lo em cache.

Antes de recorrer ao cache, mude onde as coisas ficam. Before You memo(), de Dan Abramov, descreve duas técnicas que não precisam de memoização, e elas continuam sendo o melhor primeiro passo:

Mover o estado para baixo. Se um pequeno pedaço da interface é dono do estado, dê a esse pedaço o seu próprio componente, para que só ele re-renderize (qualquer versão do React com hooks, 16.8+):

// Before: typing re-renders <SlowTree /> too
function App() {
  const [text, setText] = useState('');
  return (<><input value={text} onChange={(e) => setText(e.target.value)} /><SlowTree /></>);
}

// After: the state lives in a component that renders only the input
function SearchBox() {
  const [text, setText] = useState('');
  return <input value={text} onChange={(e) => setText(e.target.value)} />;
}
function App() { return (<><SearchBox /><SlowTree /></>); }

Elevar o conteúdo. Quando o estado precisa ficar em um wrapper que envolve a parte lenta (um contêiner de rolagem, um painel redimensionável), deixe o pai do wrapper criar o elemento lento e passá-lo como children (qualquer versão do React):

function ScrollArea({ children }: { children: React.ReactNode }) {
  const [y, setY] = useState(0);                    // updates on every scroll event
  return <div onScroll={(e) => setY(e.currentTarget.scrollTop)}>{children}</div>;
}
// <SlowTree /> is created here, by a component that does not render when y changes,
// so React receives the same element object and skips it.
<ScrollArea><SlowTree /></ScrollArea>

Isso funciona por causa da identidade dos elementos: o elemento criado pelo componente externo é o mesmo objeto na re-renderização do componente interno, então não há nada a comparar nem a refazer. children é apenas uma prop, e o mesmo vale para qualquer prop que carregue um elemento (icon={<Icon />}, footer={<Footer />}). Elementos como props também mantêm um componente simples: em vez de iconColor, iconSize e outras props de configuração, quem chama passa o elemento pronto. Quando o wrapper precisa entregar algum dado ao elemento (o estado de hover), uma render prop (renderIcon={(hovered) => ...}) resolve, embora um hook personalizado seja hoje, muitas vezes, a forma mais limpa de compartilhar lógica com estado.

Duas coisas que minam essas técnicas: um hook personalizado não isola renderizações, porque uma atualização de estado em qualquer ponto dentro de um hook re-renderiza o componente que o chama, e um hook que chama outro repassa a atualização pela cadeia; e assinar algo que muda com frequência (posição de rolagem, tamanho da janela, um store global) em um componente grande re-renderiza tudo dele. Os componentes de ordem superior (funções que recebem um componente e devolvem um aprimorado) são a forma de compartilhar comportamento de antes dos hooks; ainda servem para envolver um grupo de componentes com o mesmo log ou a mesma interceptação de eventos, mas um hook ou um componente wrapper costuma ser mais simples.

3. Memoização e o que o React Compiler muda

Em resumo. A memoização só ajuda quando algo compara a prop. O compilador agora faz a maior parte; saiba verificar o que ele fez.

O React compara objetos, arrays e funções por referência (Object.is), não por conteúdo, nos arrays de dependências e nas props de React.memo. Uma função ou um objeto criado no corpo de um componente é um valor novo a cada renderização. As ferramentas:

FerramentaO que mantémQuando importa
useMemo(fn, deps)o resultado de fn até que deps mudemum cálculo caro, ou um valor usado como dependência ou como prop de um componente memoizado
useCallback(fn, deps)a própria funçãoo mesmo, para funções
React.memo(Component)pula a renderização quando as props são shallow-equal e a renderização foi causada pelo paium componente caro cujo pai renderiza com frequência com dados inalterados

Por que a memoização manual é mais difícil do que parece, um ponto levantado por Erikson e, longamente, por TkDodo ("a batalha morro acima da memoização"):

  1. Memoizar uma prop é inútil se nada a compara: o componente receptor precisa estar envolvido em React.memo, usar a prop como dependência de um hook ou passá-la a algo que o faça.
  2. Uma única prop instável derrota o React.memo do componente inteiro. Objetos, arrays, funções e children em JSX escritos inline são referências novas a cada renderização, e um novo valor de reserva como value ?? [] pode quebrar a estabilidade outra vez. Alguém que adicione uma prop depois pode desfazer o benefício sem perceber.
  3. O React.memo só impede re-renderizações causadas pelo pai. Uma mudança de estado ou de contexto dentro do componente ainda o renderiza.
  4. Comparar não é de graça. Meça primeiro; a memoização compensa para trabalho lento, não para expressões baratas.

Desde 2025: o React Compiler. O React Compiler 1.0 se tornou estável em 7 de outubro de 2025. É uma ferramenta de tempo de build que analisa componentes e hooks e adiciona memoização automaticamente, inclusive em casos que a memoização manual não alcança, como o código depois de um return antecipado. Ele suporta o React 17 e superiores, é instalado como um plugin do Babel (babel-plugin-react-compiler) fixado em uma versão exata, é oferecido pelos templates do Vite, do Next.js e do Expo, e suas regras de lint vêm pelo eslint-plugin-react-hooks. A orientação oficial:

SituaçãoOrientação do anúncio do React Compiler 1.0
Código novoconfie no compilador; adicione useMemo e useCallback só onde precisar de controle preciso, por exemplo um valor usado como dependência de um efeito para que o efeito não rode vezes demais
Código existentedeixe a memoização existente no lugar (removê-la pode mudar o que o compilador produz), ou remova-a só depois de testar com cuidado
Código que quebra as Regras do Reacto compilador pode mudar o comportamento, como um efeito rodando mais ou menos vezes; com pouca cobertura de testes, fixe a versão exata do compilador

O anúncio não diz nada específico sobre o React.memo, então não faço afirmação sobre ele. O que decorre disso: entender por que a memoização funciona e falha continua sendo o que você precisa para ler a saída do compilador e depurá-la; o que envelhece é o conselho de escrever a maior parte dela à mão. As correções estruturais (seção 2) continuam ajudando, porque removem trabalho em vez de guardá-lo em cache. E meça: o profiler do React DevTools e, desde a 19.2, as Performance Tracks do Chrome DevTools mostram o que renderizou e por quê. A palestra posterior de Erikson sobre o comportamento de renderização do compilador é um bom próximo passo.

Verificando o que o compilador fez. "O compilador está ligado" não é o mesmo que "o meu componente foi compilado", e um componente que o compilador pula simplesmente roda sem memoização automática, sem nenhum erro em tempo de execução. Quatro verificações, da mais barata à mais detalhada (react.dev, Installation e Configuration):

  1. React DevTools. Em desenvolvimento, os componentes que o compilador otimizou mostram um selo "Memo ✨" ao lado do nome. Um componente quente sem ele não foi compilado.
  2. A saída do build. O código compilado importa c as _c de react/compiler-runtime e guarda os resultados em um array de cache (const $ = _c(1)), então uma busca rápida por compiler-runtime no arquivo gerado diz se um arquivo chegou a ser transformado.
  3. Lint. As regras do compilador vêm no eslint-plugin-react-hooks (o preset recommended-latest). A documentação diz o que um erro significa: o compilador vai pular a otimização daquele componente ou hook específico, o que é seguro e deixa o resto do código otimizado. Assim, um erro de lint em um componente é o motivo habitual de um selo ausente.
  4. Eventos de build. A opção logger recebe uma função logEvent(filename, event), de modo que um build pode imprimir o que foi compilado (o exemplo da documentação verifica event.kind === 'CompileSuccess'); panicThreshold: 'none' faz o build pular um componente problemático em vez de falhar.

React 17 ou posterior com babel-plugin-react-compiler (Compiler 1.0, estável). O motivo mais comum de um componente ser pulado é um código que quebra as Regras do React, em geral alterando durante a renderização algo que não lhe pertence:

function Leaderboard({ scores }: { scores: number[] }) {
  const top = scores.sort((a, b) => b - a).slice(0, 3);   // sort() mutates the PROP array in place: a Rules of React violation
  return <ol>{top.map((s) => <li key={s}>{s}</li>)}</ol>;  // the lint rule reports it; the compiler skips this component
}
// Fix: copy first. `[...scores].sort(...)` or `scores.toSorted(...)` leaves the prop untouched.

Para tirar um componente do compilador de propósito, coloque a diretiva "use no memo" como primeira instrução do seu corpo (a forma da documentação de excluir um componente que se comporta mal). Para ir no sentido contrário, compilationMode: 'annotation' compila apenas as funções marcadas com "use memo", que é o caminho suportado para adotar o compilador um componente de cada vez.

Antes e depois no Profiler. Não incluí um trace, porque os números dependem da sua aplicação, mas a comparação é fácil de fazer por conta própria: (1) no React DevTools, abra o Profiler e, nas configurações dele, ative Record why each component rendered while profiling; (2) grave uma interação fixa, como digitar cinco caracteres no campo de busca; (3) repita com o compilador desligado e ligado, ou antes e depois de uma mudança estrutural da seção 2. Compare três coisas: quantos componentes se acenderam em cada commit (uma barra cinza significa que não renderizou), quais e o motivo mostrado para cada um (props mudaram, estado mudou, o pai renderizou) e o tempo de commit dos commits mais lentos. Se o compilador ou a sua mudança funcionou, os componentes que não dependem do texto digitado devem aparecer em cinza. Meça em um build de produção quando puder, porque os builds de desenvolvimento (inclusive com a dupla renderização do Strict Mode) são mais lentos e diferem.

4. Quando ainda está lento: medir, urgência e fazer menos

Em resumo. Depois de estrutura e cache, você pode renderizar o mesmo trabalho mais tarde (transições), renderizar menos dele (virtualização) ou não renderizá-lo até ser preciso. Antes, meça com a mesma interação fixa todas as vezes.

Meça o seu próprio app. Dois pequenos auxiliares mostram o que renderiza e por quê. São ilustrativos e feitos para desenvolvimento: o <Profiler> não faz nada em um build normal de produção, a menos que você use o build de profiling do React DOM.

import { Profiler, useEffect, useRef, type ProfilerOnRenderCallback, type ReactNode } from 'react';

const totals = new Map<string, { commits: number; ms: number }>();
const onRender: ProfilerOnRenderCallback = (id, _phase, actualDuration) => {
  const t = totals.get(id) ?? { commits: 0, ms: 0 };
  totals.set(id, { commits: t.commits + 1, ms: t.ms + actualDuration });   // actualDuration: time spent rendering this subtree
};

/** Wrap a subtree; after one interaction call `report()` in the console. */
export function Audit({ id, children }: { id: string; children: ReactNode }) {
  return <Profiler id={id} onRender={onRender}>{children}</Profiler>;
}
export const report = () => console.table(Object.fromEntries(totals));

/** Logs which props changed since the last render; "none" means state, context or the parent caused it. */
export function useRenderCause(name: string, props: Record<string, unknown>) {
  const previous = useRef(props);
  useEffect(() => {                                        // compared in an effect: refs must not be read during render
    const changed = Object.keys(props).filter((k) => !Object.is(previous.current[k], props[k]));
    console.log(`${name} rendered; props changed: ${changed.join(', ') || 'none'}`);
    previous.current = props;
  });
}

Use-o sempre do mesmo jeito: envolva a tela em <Audit>, faça uma interação fixa (digite cinco caracteres), chame report() e anote os commits e os milissegundos. Repita depois de cada mudança. Os números só têm sentido uns em relação aos outros, na sua máquina, no mesmo build.

Urgente e não urgente: transições. Digitar precisa parecer instantâneo; atualizar uma lista longa pode esperar um instante. O useTransition marca uma atualização de estado como não urgente, para que o React possa começar a renderizá-la, abandonar essa renderização se chegar uma atualização urgente (a próxima tecla) e mostrar o resultado quando terminar (React 18 ou posterior):

function FilterableList({ items }: { items: Item[] }) {
  const [query, setQuery] = useState('');                  // urgent: what the field shows
  const [shown, setShown] = useState(items);               // not urgent: what the big list shows
  const [isPending, startTransition] = useTransition();
  return (
    <>
      <input
        value={query}
        onChange={(e) => {
          setQuery(e.target.value);                        // painted at once
          startTransition(() => setShown(filterItems(items, e.target.value)));   // may be interrupted by the next keystroke
        }}
      />
      <Rows items={shown} stale={isPending} />              {/* dim the list while it catches up */}
    </>
  );
}

Quando o valor vem de um lugar que você não consegue envolver em uma transição (uma prop, um hook personalizado), o useDeferredValue dá a você uma cópia defasada:

const deferredQuery = useDeferredValue(query);              // old value during an urgent update, new value a moment later
return <><input value={query} onChange={...} /><SlowRows query={deferredQuery} /></>;
const SlowRows = memo(function SlowRows({ query }: { query: string }) { /* the slow part */ });   // memo is what lets it skip the urgent pass

O que saber antes de usar qualquer um dos dois:

Fazer menos. Quando o problema é a própria lista, renderizá-la mais rápido é a alavanca errada; renderize menos linhas.

TécnicaO que ela removeO que ela custa
Janelamento (@tanstack/react-virtual, react-window)trabalho do React e nós do DOM das linhas fora da área visívela busca do navegador não vê linhas não renderizadas; as alturas das linhas precisam ser conhecidas ou medidas; a restauração da rolagem e o foco do teclado em linhas removidas exigem tratamento; leitores de tela precisam de aria-rowcount e aria-rowindex ou equivalentes
Paginação ou "carregar mais"dados buscados e linhas renderizadaso modelo de navegação muda, mas é o mais simples e o mais acessível
content-visibility: auto com contain-intrinsic-sizeo layout e a pintura do navegador das seções fora da telao React ainda executa os componentes, então o custo de JavaScript continua; verifique o suporte nos navegadores-alvo
<Activity mode="hidden"> (19.2 ou posterior)trabalho das partes da interface que o usuário não vê; os efeitos são desmontados e as atualizações adiadas enquanto o estado é mantidoa memória continua em uso; serve para abas e próximas páginas prováveis, não para listas longas

Uma regra razoável: abaixo de algumas centenas de linhas baratas, linhas memoizadas são mais simples e seguras; com milhares, ou com linhas caras, o janelamento compensa a sua complexidade. Decida pela auditoria, não só pelo número de linhas.

Quando não é renderização. Se a auditoria mostra pouco tempo de renderização mas a interação continua lenta, o custo é computação em um manipulador (ordenar ou analisar um conjunto grande de dados), e ele aparece no painel Performance do navegador, não no Profiler. Mova-o para um Web Worker ou para o servidor, ou faça uma vez e guarde o resultado, em vez de recalculá-lo a cada tecla.

Um caso trabalhado: a tabela filtrável. Digitar em um campo de filtro acima de uma tabela de 5.000 linhas trava. Um caminho de descida pela escada, com o que procurar na auditoria em cada passo (os números são seus para registrar):

PassoMudançaO que a auditoria deve mostrar
0Gravar: <Audit> em volta da página, digitar cinco caracteres, report()um commit de Row por linha por tecla, com a causa "nenhuma" (o pai renderizou)
1Estrutura: manter query no componente que precisa dele e subir o resto do conteúdo da tabela como childreno cabeçalho e a barra lateral deixam de aparecer
2Cache: compilador, ou memo em Row com props estáveisas linhas que sobrevivem ao filtro deixam de renderizar; as que aparecem ainda custam
3Reordenar: useDeferredValue(query) para a tabelao campo continua responsivo; a tabela o alcança um instante depois
4Fazer menos: janelar as linhassó as linhas visíveis renderizam, qualquer que seja o tamanho dos dados
5Mover: se filtrar 5.000 registros já é lento, filtrar em um workero manipulador da tecla volta a ser curto no painel Performance

A maioria das telas reais para no passo 1 ou 2. O sentido da escada é você saber qual é o próximo movimento e o que ele vai lhe custar antes de fazê-lo.

5. O estado pertence a uma posição: identidade, chaves e resets

Em resumo. O estado pertence a uma posição na árvore. As chaves dão identidade, e mudar uma chave redefine o estado.

O React mantém o estado de um componente conforme onde ele está na árvore, não onde aparece no JSX (documentação do React, "Preserving and Resetting State"). Regras que decorrem disso:

Quatro consequências que causam bugs reais:

  1. Nunca defina um componente dentro de outro componente. A função interna é uma função nova, portanto um tipo novo, a cada renderização; o React a desmonta e a remonta toda vez, perdendo o estado, o foco e os efeitos em execução. Declare os componentes no nível superior.
  2. Não use o índice do array como chave em listas que podem ser reordenadas, filtradas ou receber inserções: o estado (o texto de um campo, uma caixa de seleção) fica com a posição, não com o dado. Use o id do registro.
  3. Não gere chaves durante a renderização (Math.random(), crypto.randomUUID()): cada renderização produz chaves novas, então todos os itens são remontados.
  4. Uma chave também é um botão de reset. Mudá-la faz o React tratar o componente como outro: <Profile userId={id} key={id} /> descarta o estado do formulário do usuário anterior quando id muda. A documentação do React prefere isso a um efeito que tenta redefinir o estado à mão, o qual renderiza primeiro uma vez com o estado obsoleto. Uma chave não é uma prop; o componente nunca a recebe.

As chaves importam mais quando os itens são caros ou estão envolvidos em React.memo, porque uma chave errada faz um item memoizado re-renderizar ou perder o estado.

6. Compartilhar estado: props, Context, reducers e stores

Em resumo. O Context re-renderiza todo consumidor a cada mudança. Divida-o, ou use um store com seletores, mas antes pergunte quem deve ser dono do estado.

O Context passa um valor para o fundo da árvore sem precisar atravessar cada nível, o que também evita renderizar os componentes do meio. O custo, explicado por Erikson: um provider compara o seu value por referência, e todo componente que lê o contexto re-renderiza quando ele muda, mesmo que use apenas um campo, e o React.memo não impede isso. Um provider que monta o seu valor na renderização (value={{ user, setUser }}) cria um objeto novo a cada renderização, de modo que todos os consumidores re-renderizam sempre que o provider renderiza. O Context é uma forma de entregar um valor, não uma ferramenta de gerenciamento de estado: não tem seletores nem assinatura de fatias.

O que ajuda:

O que mudou no React 19:

AntesAgora
<ThemeContext.Provider value={x}><ThemeContext value={x}>; a forma .Provider ainda funciona, e a equipe planeja um codemod e uma futura descontinuação
useContext(Ctx) só no nível superioruse(Ctx) também lê contexto e, diferentemente dos hooks, pode ser chamado condicionalmente, depois de um return antecipado, por exemplo
um wrapper de cliente para fornecer contexto a partir de um Server Componentdesde a 19.3, os Server Components podem renderizar diretamente um provider de contexto de um módulo 'use client'

Nada disso muda a regra de que os consumidores re-renderizam quando o valor muda; dividir continua sendo trabalho de projeto.

O Context não substitui a propriedade do estado. Memoizar o valor do provider impede as re-renderizações causadas pelo pai do provider; não impede que um consumidor re-renderize quando o valor que ele lê realmente muda. Antes de recorrer a qualquer das correções acima, pergunte quem deve ser dono do estado: se apenas dois componentes precisam de count, mantenha-o no pai comum mais próximo e passe-o como props. O Context serve para valores que mudam raramente e são necessários longe (tema, idioma, o usuário autenticado). Quatro formas de compartilhar count e name entre um CountView, um NameView e um ResetButton:

Funciona no React 16.8+ (hooks, createContext); a forma <Ctx value> exige o React 19. O useSyncExternalStore exige o React 18+. Ilustrativo.

// A. One context, memoized value: every consumer re-renders when EITHER field changes.
const AppCtx = createContext<{ count: number; name: string; reset(): void } | null>(null);

// B. Split contexts: state and actions apart, and one context per field that changes independently.
const CountCtx = createContext(0);
const NameCtx = createContext('');
const ActionsCtx = createContext<{ reset(): void }>({ reset() {} });   // stable: provide it with useMemo/useCallback

// C. An external store with selectors: a component subscribes to the slice it reads.
function useStore<T>(select: (s: State) => T): T {
  return useSyncExternalStore(store.subscribe, () => select(store.getState()));   // select must return a stable value
}
const count = useStore((s) => s.count);

// D. Ordinary props: the owner holds the state; pass only what each child needs.
function Owner() {
  const [count, setCount] = useState(0);
  const [name, setName] = useState('');
  return <><CountView count={count} /><NameView name={name} /><ResetButton onReset={() => { setCount(0); setName(''); }} /></>;
}

Quem re-renderiza quando só count muda (supondo que o componente provider receba os seus filhos como props, seção 2), pelas regras documentadas em react.dev e no guia de Erikson (isto é raciocínio a partir dessas regras, não uma medição; confirme no Profiler para a sua árvore):

AbordagemCountViewNameViewResetButtonCusto e ressalva
A. um contextosimsim (lê o mesmo contexto)simo mais simples; todo consumidor acompanha toda mudança
B. contextos divididossimnãonão (lê só as ações estáveis)mais providers para escrever e manter na ordem certa
C. store com seletoressimnãonãouma dependência nova ou um pequeno store para manter; os seletores precisam devolver valores estáveis
D. só propssimsim, a menos que esteja memoizado ou o seu elemento seja criado acima do donosim, a menos que esteja memoizado (o seu onReset é uma função nova)não precisa de nenhum mecanismo extra, mas a propriedade do estado e a passagem de props viram o problema de projeto

Nenhuma das quatro é sempre a certa. As props são o melhor padrão enquanto a árvore é rasa; contextos divididos ou um store aparecem quando muitos componentes distantes leem um valor que muda com frequência.

7. Efeitos, eventos e valores obsoletos

Em resumo. Uma função guarda os valores da renderização que a criou. Valores obsoletos vêm daí, e têm quatro correções, em ordem de preferência.

Escolha primeiro a ferramenta certa. "You Might Not Need an Effect", da documentação do React, é a melhor lista curta de erros: os efeitos servem para sincronizar com sistemas externos (a rede, um widget que não é React, o navegador). Derive valores durante a renderização em vez de copiá-los para o estado; faça o trabalho causado pelo usuário no manipulador de evento, porque, quando um efeito roda, você já não sabe o que o usuário fez; evite cadeias de efeitos que definem estado para disparar uns aos outros; redefina o estado com key (seção 5) em vez de um efeito; e assine stores externos com useSyncExternalStore.

Closures. Uma função criada dentro de um componente é uma closure: ela guarda referências às variáveis daquela renderização, como uma fotografia (a MDN a define como uma função empacotada com o seu ambiente léxico, criada cada vez que uma função é criada). Quando uma função de longa duração roda mais tarde, ela enxerga a fotografia antiga, a menos que seja criada de novo. Esse é o bug da closure obsoleta (hooks, React 16.8+):

const [count, setCount] = useState(0);
useEffect(() => {
  const id = setInterval(() => console.log(count), 1000);   // closes over THIS render's count
  return () => clearInterval(id);
}, []);   // never re-created, so it logs the first value forever

Reproduzi a mecânica em JavaScript puro (closures.js): três temporizadores criados de maneiras diferentes, depois de o valor mudar de 0 para 1 e para 2.

Como o callback é criadoValor que ele enxerga depois da última mudança
uma vez, fechando sobre a primeira renderização (lista de dependências vazia)0 (obsoleto)
uma vez, lendo uma ref atualizada após cada renderização2
recriado sempre que o valor muda (a lista de dependências o inclui)2

Correções, em ordem de preferência:

  1. Liste a dependência; a regra react-hooks/exhaustive-deps a encontra, e a documentação desaconselha suprimi-la, porque a supressão esconde exatamente esses bugs. O efeito faz a limpeza e reinicia com os valores novos.
  2. Use uma atualização funcional (setCount((c) => c + 1)) para que o valor não seja necessário.
  3. Use useEffectEvent (documentado com o React 19.2): ele separa "o que fazer" de "quando rodar de novo". O seu corpo sempre enxerga as props e o estado mais recentes, mas não é reativo, então não reinicia o efeito. O exemplo da documentação mantém uma conexão de chat ligada ao roomId, enquanto uma notificação de "conectado" lê o theme atual sem reconectar quando o tema muda. Limites da documentação: chame-o apenas dentro de efeitos, nunca o passe a outros componentes ou hooks e omita-o dos arrays de dependências (o plugin de lint impõe isso).
  4. Guarde a função mais recente em uma ref e leia ref.current a partir do callback de longa duração. É o padrão mais antigo, ainda útil fora dos efeitos; o useEffectEvent agora cobre o caso dos efeitos.

Debouncing e throttling mostram o problema pelo outro lado. Uma função com debounce guarda um temporizador, então deve ser criada uma vez por componente; criada no corpo da renderização, cada renderização ganha o seu próprio temporizador e nada sofre debounce. Mas, criada uma vez, ela fecha sobre a primeira renderização. No closures.js, "digitei" r, re, rea, reac, react com dez milissegundos de intervalo em um debounce de 50 ms:

De onde vem a função com debounceBuscas realizadas
criada no corpo da renderização (uma nova a cada renderização)5: r, re, rea, reac, react; nada sofreu debounce
criada uma vez, fechando sobre a primeira renderização1, com o texto errado: r
criada uma vez, chamando a função mais recente por meio de uma ref1, correta: react

Mantenha a função com debounce estável e dê a ela um meio de alcançar dados atuais. Muitas vezes é mais simples aplicar debounce a um valor (um hook useDebouncedValue que atualiza depois de um atraso e cancela o seu temporizador na limpeza). O useDeferredValue e as transições reduzem o custo de renderização; não reduzem as requisições de rede.

8. Refs

Em resumo. Uma ref é uma caixa que sobrevive às renderizações e não re-renderiza. No React 19 ela é uma prop comum.

Uma ref é um objeto mutável, { current: value }, que continua o mesmo entre as renderizações. Ela difere do estado em dois pontos que decidem quando usá-la: alterá-la não re-renderiza, e a alteração é síncrona e visível na hora, enquanto as atualizações de estado são agendadas e aplicadas na renderização seguinte. Por isso as refs guardam valores que não aparecem na tela: um id de temporizador, o valor anterior, um nó do DOM, o callback mais recente (seção 7). A documentação do React acrescenta uma regra: não leia nem escreva ref.current durante a renderização, apenas em manipuladores de evento e efeitos, ou o componente deixa de ser puro; as regras de lint do compilador (refs) sinalizam isso.

Alcançar o DOM. const inputRef = useRef<HTMLInputElement>(null), depois <input ref={inputRef} />; após o commit, inputRef.current é o elemento e inputRef.current?.focus() funciona a partir de um manipulador.

Passar uma ref ao seu próprio componente é onde o React 19 mudou as coisas:

Antes (React 18)Agora (React 19)
um componente de função não podia receber ref; você o envolvia em forwardRef((props, ref) => ...)ref é uma prop comum: function MyInput({ placeholder, ref }) { return <input placeholder={placeholder} ref={ref} />; }
forwardRef obrigatórioforwardRef ainda funciona, mas já não é necessário; a documentação o marca como descontinuado e um codemod está planejado

Outras mudanças: callbacks de ref podem devolver uma função de limpeza (ela roda na desmontagem, e o React então deixa de chamar a ref com null), então escreva ref={(el) => { instance = el; }} com corpo em bloco, já que o TypeScript agora rejeita um retorno implícito; o useRef exige um argumento no TypeScript (useRef(undefined)); as refs em string foram removidas e element.ref está descontinuado. Desde a 19.3, uma ref em um <Fragment> dá acesso a um grupo de filhos do DOM (addEventListener, focus, scrollIntoView) sem um elemento wrapper.

Uma API imperativa. Quando um pai realmente precisa comandar um filho (focus(), shake(), scrollTo), exponha alguns métodos com useImperativeHandle(ref, () => ({ shake, focus }), []) em vez de entregar o nó do DOM inteiro. Use com moderação: a maior parte da comunicação deve passar por props e estado.

9. Layout, pintura e portais

Em resumo. Meça antes da pintura com useLayoutEffect; escape do corte com um portal, e lembre que os eventos seguem a árvore do React.

useEffect ou useLayoutEffect. O useEffect roda depois de o navegador ter tido a chance de pintar; o useLayoutEffect roda depois de o React atualizar o DOM, mas antes de o navegador pintar (documentação do React). Se um efeito mede um elemento e depois define estado para posicionar ou redimensionar algo, fazer isso em useEffect pode mostrar um quadro no lugar errado, um tremor visível, e o useLayoutEffect o elimina. O aviso da documentação: o seu código e as atualizações de estado que ele dispara bloqueiam a pintura, então use-o apenas para medir e posicionar.

No servidor, os efeitos não rodam, e o useLayoutEffect dispara o aviso "useLayoutEffect does nothing on the server", já que não há layout a medir; o tremor pode voltar em aplicações renderizadas no servidor. A documentação lista as opções:

OpçãoUse quando
trocá-lo por useEffecto HTML do servidor é aceitável até o efeito rodar
renderizar o componente só no cliente com use(browser()) (novo na 19.3)ele não pode ser renderizado no servidor; um fallback do Suspense vai para o HTML
renderizá-lo depois da montagem (um estado isMounted definido em um efeito)o padrão mais antigo e universal
useSyncExternalStoreo efeito só lia um valor externo, não o layout

Portais. Um modal, tooltip ou dropdown dentro de um contêiner com overflow: hidden, ou dentro de um pai que cria um contexto de empilhamento (position com z-index, transform, opacity abaixo de 1 e outros), pode ser cortado ou ficar preso sob outro conteúdo, qualquer que seja o seu z-index. O createPortal(children, document.body) renderiza os elementos em outro nó do DOM mantendo-os no mesmo lugar da árvore do React. Assim, o contexto e os eventos seguem a árvore do React (um clique dentro do portal dispara onClick nos seus ancestrais React), enquanto o CSS, os eventos nativos do DOM e o envio de formulários seguem a árvore do DOM: um <button> em um portal não envia nativamente o <form> sob o qual é renderizado. A documentação acrescenta um dever de acessibilidade: gerencie o foco do teclado para dentro e para fora do portal e siga as práticas de modal do WAI-ARIA. A top layer do navegador (um <dialog> nativo aberto com showModal() e a Popover API) resolve parte do mesmo problema sem um portal; verifique o suporte para os seus alvos.

10. Dados assíncronos

Em resumo. Uma cadeia de requisições custa a soma, um grupo custa a mais lenta. Respostas tardias de requisições antigas são o bug habitual, e têm curas simples.

A versão simples e seus limites. Buscar dados em um efeito é válido, e a documentação do React diz isso. Você passa a ser dono dos estados de carregamento e de erro, do cache, do cancelamento, das novas tentativas, da deduplicação e da rebusca, e a documentação aponta a busca de dados embutida em um framework como o caminho mais eficiente. Para qualquer coisa além de "buscar uma vez e esquecer", use uma biblioteca de dados (TanStack Query, SWR, RTK Query, Apollo) ou a camada de dados do seu framework. Bibliotecas não consertam a estrutura de um app, e é dela que vêm as cascatas.

Evidência nesta seção. Não há medições aqui. Os dois problemas abaixo são explicados por aritmética e por um rastreio determinístico, e os scripts do apêndice conferem a aritmética. O que você verá no seu app depende das suas latências, dos cliques dos seus usuários e do seu cache; vale então o hábito da seção 4: limite a rede nas ferramentas do desenvolvedor do navegador e registre as suas.

Cascatas (waterfalls). Uma cascata é uma cadeia de requisições em que cada uma só começa depois que a anterior termina. A documentação do TanStack Query lista as causas habituais: consultas dependentes, componentes aninhados (um pai espera os seus dados antes de renderizar um filho, então a requisição do filho começa tarde), divisão de código (o JavaScript de um componente lazy só carrega depois que o pai renderiza, e a requisição dele começa depois disso) e, com Suspense, várias consultas que suspendem no mesmo componente rodando uma depois da outra.

sequential   |-- user --|-- posts --|-- comments --|     3 x latency
together     |-- user --|
             |-- posts --|
             |-- comments --|                            1 x latency (the slowest)
FormaTempoCom 100 ms por requisição (aritmética, não medição)
n requisições, uma depois da outran × L3 requisições: 300 ms
n requisições iniciadas juntasL, a mais lenta3 requisições: 100 ms
n requisições, c conexões por vez⌈n / c⌉ × L12 requisições, 6 conexões: 200 ms

A última linha é o antigo limite do HTTP/1.1 de cerca de seis conexões por host; o HTTP/2 e o HTTP/3 multiplexam as requisições em uma só conexão e o eliminam (DNS e HTTP). Um navegador soma DNS, TLS, cache e renderização a tudo isso, e é por isso que o número real é seu para registrar.

As correções citadas pelo TanStack: reestruturar a API para que dados dependentes cheguem em uma só requisição, elevar requisições independentes a um pai para que rodem em paralelo, fazer prefetch cedo (no roteador, na navegação), buscar os dados de um componente com divisão de código junto com o seu JavaScript e fazer a busca dependente no servidor, onde a latência é menor.

Promise.all só ajuda requisições que não dependem umas das outras. Se a requisição dos posts precisa do user.id que a primeira devolve, a segunda não pode começar até a primeira terminar, qualquer que seja a sintaxe (await, .then, um hook, um loader). Só a reestruturação remove a espera: um endpoint que aceita o que você já sabe (um nome de usuário da URL), um endpoint combinado, um join no servidor, ou o prefetch de algo que você pode derivar antes (parâmetros de rota). Nem toda cascata precisa de correção: olhe a aba Rede e corrija as de maior impacto.

Condições de corrida. Uma resposta pode chegar depois da resposta de uma requisição mais nova. Em um efeito que busca por id e depois chama setData, clicar na página 2 e logo na 3 pode deixar a tela mostrando a página 2 enquanto o endereço diz 3. O bug inteiro em quatro linhas:

t = 0 ms     click page 2   request A sent
t = 10 ms    click page 3   request B sent
t = 40 ms    B answered     screen shows page 3  (correct)
t = 130 ms   A answered     naive code writes page 2 over page 3  (wrong, and it stays)

Ele precisa de duas coisas ao mesmo tempo: requisições que se sobrepõem no tempo e tempos de resposta que variam mais que o intervalo entre elas. Para duas requisições iniciadas com g ms de diferença, com tempos de resposta independentes distribuídos uniformemente entre 0 e w ms, a resposta mais antiga chega por último com probabilidade ½(1 − g/w)² quando g < w, e nunca nos outros casos. O formula.js do apêndice confere isso contra sorteios aleatórios.

Tempos de resposta distribuídos em wRequisições com g de intervaloChance de a resposta mais antiga chegar por último
40 ms10 ms28%
200 ms10 ms45%
200 ms50 ms28%
200 ms150 ms3%
40 ms50 ms ou mais0%

São valores da fórmula, não observações de um app. Leia-os pelo formato: respostas rápidas e regulares e cliques lentos escondem o bug; respostas lentas e irregulares com cliques rápidos o mostram com frequência, e um terceiro e um quarto clique somam mais pares que podem trocar de ordem. As três correções abaixo não precisam dessa tabela, porque cada uma funciona por construção: a flag de ignorar torna a escrita tardia impossível, a checagem do id a torna detectável, e o abort impede que a requisição antiga termine. Elas estão corretas qualquer que seja o tempo, e esse é o motivo de preferi-las a torcer para o tempo ser gentil.

A flag ignore é a receita da própria documentação do React: let ignore = false; no efeito, if (!ignore) setData(json) no callback e return () => { ignore = true; } como limpeza. Ela protege a correção: o resultado obsoleto simplesmente não é usado. O AbortController também evita a escrita obsoleta e pode poupar recursos, mas é preciso cuidado com o quanto ele faz (qualquer versão do React com hooks; AbortController é uma API do navegador e do Node; ilustrativo):

useEffect(() => {
  const controller = new AbortController();
  fetch(`/api/pages/${id}`, { signal: controller.signal })
    .then((r) => r.json())
    .then(setData)
    .catch((e) => { if (e.name !== 'AbortError') setError(e); });
  return () => controller.abort();          // runs before the next effect and on unmount
}, [id]);

O que abortar faz e não faz. Abortar é cancelamento do lado do cliente. Em detalhe:

Portanto conte com o abort pelo lado do cliente (nenhuma escrita obsoleta, nenhum download desperdiçado) e trate a economia no servidor como um bônus que precisa de cooperação. Use a flag de ignorar ou a checagem do id para a correção, e acrescente o abort quando cancelar o download ou o trabalho do servidor valer a pena.

Remontar com uma key (seção 5) também remove o destino dos resultados antigos. async/await muda a sintaxe, não o comportamento. Uma biblioteca de dados cuida de tudo isso, e esse é um dos melhores motivos para usar uma. (O velho aviso "Can't perform a React state update on an unmounted component" foi removido do React.)

use(), Suspense e Actions (React 19).

// Illustrative; commentsPromise comes from a loader, a cache or a Server Component, not created here.
function Comments({ commentsPromise }: { commentsPromise: Promise<Comment[]> }) {
  const comments = use(commentsPromise);       // suspends until resolved
  return <ul>{comments.map((c) => <li key={c.id}>{c.text}</li>)}</ul>;
}
<ErrorBoundary fallback={<p>Could not load comments.</p>}>
  <Suspense fallback={<p>Loading...</p>}><Comments commentsPromise={commentsPromise} /></Suspense>
</ErrorBoundary>

11. Erros

Em resumo. Os boundaries capturam apenas erros de renderização. Uma configuração completa também registra o erro e deixa o usuário tentar de novo.

Por padrão, um erro lançado enquanto o React renderiza remove a interface inteira, então alguns error boundaries em lugares sensatos (uma página, um widget, uma rota) são quase obrigatórios. A documentação do React (a referência de Component) diz o que um boundary captura e o que não captura:

FerramentaCapturaNão captura
error boundaryerros lançados durante a renderização dos componentes abaixo dele, por mais fundo que estejamerros em manipuladores de evento, em código assíncrono como setTimeout, na renderização no servidor e no próprio boundary (uma exceção: erros lançados dentro de uma função passada a startTransition são capturados)
try/catcherros em manipuladores de evento, callbacks e código com awaiterros lançados durante a renderização de componentes filhos; não dá para envolver de forma útil o return de um componente

O ciclo completo, uma vez. Capturar o erro é o meio da história; uma tela útil também o registra e deixa o usuário se recuperar. O exemplo abaixo acompanha uma requisição que falha, do início até a nova tentativa (ilustrativo; o boundary vem do pacote da comunidade react-error-boundary, que esconde o componente de classe, e o use() exige o React 19; reportError representa a sua chamada de logging):

const cache = new Map<string, Promise<Comment[]>>();   // a Suspense-compatible cache: the same key gives the same promise
function loadComments(postId: string, attempt: number) {
  const key = `${postId}:${attempt}`;                   // a new attempt is a new key, so a retry makes a new request
  if (!cache.has(key)) {
    cache.set(key, fetch(`/api/posts/${postId}/comments`).then((r) => {
      if (!r.ok) throw new Error(`HTTP ${r.status}`);   // fetch does NOT reject on 404 or 500: turn them into errors yourself
      return r.json();
    }));
  }
  return cache.get(key)!;                               // (a real cache would also expire entries)
}
function Comments({ postId, attempt }: { postId: string; attempt: number }) {
  const comments = use(loadComments(postId, attempt)); // a rejected promise is thrown here, during render
  return <ul>{comments.map((c) => <li key={c.id}>{c.text}</li>)}</ul>;
}
export function CommentsPanel({ postId }: { postId: string }) {
  const [attempt, setAttempt] = useState(0);
  return (
    <ErrorBoundary
      resetKeys={[postId, attempt]}                                          // recover when the post or the attempt changes
      onError={(error, info) => reportError(error, info.componentStack)}     // 3. logging
      fallbackRender={() => (                                                // 4. what the user sees
        <div role="alert">
          <p>Could not load comments.</p>
          <button onClick={() => setAttempt((a) => a + 1)}>Try again</button> {/* 5. retry */}
        </div>
      )}
    >
      <Suspense fallback={<p>Loading...</p>}><Comments postId={postId} attempt={attempt} /></Suspense>
    </ErrorBoundary>
  );
}
PassoO que aconteceQuem trata
1. A requisição falhaa promise é rejeitada (um erro de rede, ou o Error lançado para um status inválido)o seu loader
2. O use() a lêa rejeição é lançada durante a renderização, então o boundary mais próximo a capturao error boundary
3. Loggingo onError recebe o erro e a pilha de componentes; no React 19, o onCaughtError da raiz também o vêo seu serviço de relatórios
4. Fallbacko boundary renderiza a mensagem e o botão; o resto da página continua funcionandoo boundary
5. Nova tentativa e recuperaçãoo clique incrementa attempt; a chave nova faz uma requisição nova; resetKeys mudou, então o boundary é redefinido e o Suspense mostra o estado de carregamento de novo; o sucesso substitui o fallbacka chave do cache e resetKeys

Em código real, acrescente um limite (poucas tentativas, com um atraso crescente) para que um servidor fora do ar não seja atingido em um laço apertado, e registre a falha final. Uma biblioteca de dados dá a maior parte disso sem que você escreva o cache: o TanStack Query tem throwOnError e um boundary de reset exatamente para esse par, e a maioria dos frameworks tem um componente de erro no nível da rota.

Quando relançar o erro durante a renderização se justifica. Lançar o erro na renderização (o padrão useAsyncError abaixo, ou o showBoundary do hook useErrorBoundary do react-error-boundary, que faz o mesmo e é a melhor escolha do que escrever à mão) se justifica quando a falha veio de um lugar que um boundary não enxerga (um manipulador de evento, um temporizador, um .then fora da renderização) e o componente não consegue continuar de forma útil, de modo que você quer o fallback inteiro. É a ferramenta errada para erros que o usuário pode corrigir ali mesmo, como uma mensagem de validação de formulário ou um salvamento que falhou com um botão "tentar de novo" ao lado do formulário: trate-os com estado comum e mantenha a tela. E, quando o caminho suportado existe, use-o: o loader de um framework e o componente de erro da rota, ou a opção de erro da biblioteca, já entregam logging, nova tentativa e recuperação ligados entre si.

Um boundary ainda é um componente de classe (getDerivedStateFromError para mostrar o fallback, que deve ser puro, e componentDidCatch para efeitos colaterais como logging); não existe um hook para isso. Escreva uma classe reutilizável ou use o pacote da comunidade react-error-boundary, como a documentação sugere. Para levar erros assíncronos a um boundary, capture-os e relance-os durante uma renderização, onde o boundary pode vê-los:

function useAsyncError() {
  const [, setState] = useState();
  return useCallback((e: unknown) => setState(() => { throw e; }), []);   // thrown inside a state updater, i.e. during render
}

React 19 e posteriores. O que mudou no React 19: os erros de renderização já não são relançados; os erros não capturados vão para window.reportError e os capturados para console.error, e novas opções da raiz permitem se conectar: onCaughtError (um boundary capturou), onUncaughtError (nada capturou) e o já existente onRecoverableError. Passe-as para createRoot ou hydrateRoot e envie os erros ao seu serviço de logging. Os erros também são registrados uma única vez, com informação completa. Com use() e Suspense, combine um boundary do Suspense com um error boundary, como no exemplo acima.

12. O que é novo desde o React 18

VersãoDataO que importa para este guia
React 19.05 dez 2024ref como prop; limpeza de ref; use(); Actions, useActionState, useOptimistic, useFormStatus; <Context value>; onCaughtError e onUncaughtError; pre-warming do Suspense
React 19.21 out 2025useEffectEvent; <Activity> (esconde parte da interface com mode="hidden": os efeitos são desmontados e as atualizações adiadas, o estado é mantido, e as próximas páginas prováveis podem ser pré-renderizadas); cacheSignal para Server Components; Performance Tracks no Chrome DevTools
React Compiler 1.07 out 2025memoização automática (seção 3)
React 19.39 set 2026<ViewTransition> e addTransitionType estáveis; refs em Fragment; use(browser()); suporte a Trusted Types; Server Components podem renderizar providers de contexto

De qual versão um exemplo precisa? A tabela de lançamentos mistura três tipos de mudança, e quem usa um React mais antigo pode copiar algo que não roda para si. Use esta lista antes de colar código:

RecursoExigeTipo
Hooks, createContext, React.memo, useLayoutEffect, portais, error boundaries (de classe), AbortController em efeitosReact 16.8 ou posterior (portais 16.0; error boundaries 16.0)núcleo estável
useSyncExternalStore, useDeferredValue, transiçõesReact 18 ou posteriornúcleo estável
ref como prop, <Ctx value>, use(), Actions, useActionState, useOptimistic, onCaughtErrorReact 19.0 ou posteriornúcleo estável; não existe no React 18
useEffectEvent, <Activity>React 19.2 ou posteriornúcleo estável; não existe no React 19.0 nem no 19.1
use(browser()), <ViewTransition>, refs em FragmentReact 19.3núcleo estável, a versão mais recente
React Compilero seu próprio pacote, babel-plugin-react-compiler, instalado no builduma ferramenta de build, não parte do pacote react; suporta o React 17 e superiores
Server Components, Server Functionsum framework ou bundler que os implemente (Next.js, React Router e outros)exige o framework; não disponível em uma configuração apenas de cliente
react-error-boundary, TanStack Query, Zustandas versões da própria bibliotecabibliotecas de terceiros, não o React

Se você está no React 18, os padrões do guia ainda valem, mas use as formas mais antigas: forwardRef, <Ctx.Provider>, useEffect com uma ref no lugar do useEffectEvent, e uma flag ignore ou uma biblioteca de dados no lugar do use().

Segurança: Server Components. Em dezembro de 2025, a equipe do React divulgou a CVE-2025-55182, uma falha de execução remota de código sem autenticação (CVSS 10.0) nos React Server Components, na forma como o servidor decodifica as requisições aos endpoints de Server Functions. Ela afetava react-server-dom-webpack, -parcel e -turbopack nas versões 19.0, 19.1.0, 19.1.1 e 19.2.0 e os frameworks que os incluem (Next.js, React Router, Waku e outros), e foi corrigida nas versões 19.0.1, 19.1.2 e 19.2.1; avisos posteriores trataram de negação de serviço e exposição de código-fonte e são corrigidos no mesmo caminho de atualização. Aplicações sem servidor, ou sem um framework ou bundler que suporte Server Components, não foram afetadas. A lição é operacional: se você usa Server Components ou Server Functions, mantenha o React, os seus pacotes de servidor e o seu framework na última versão de patch, e não trate mitigações no nível do host como substituto. Veja segurança de aplicações web para os hábitos gerais.

Os Server Components são um tema grande que este guia deixa de fora. Eles rodam apenas no servidor, podem ler dados diretamente e não enviam JavaScript próprio ao cliente; os Client Components (marcados com 'use client') concentram a interatividade. Tudo o que foi dito acima sobre re-renderizações, refs e efeitos vale para os Client Components.

13. Onde aprender mais

Nenhuma fonte cobre tudo isso, e as fontes divergem na ênfase, então leia mais de uma:

FonteBoa para
react.dev (Learn e Reference): "Preserving and Resetting State", "You Might Not Need an Effect", "Separating Events from Effects", as referências de createPortal, useLayoutEffect e Componentas regras atuais e autorizadas, e os posts de lançamento para o que mudou
Mark Erikson, A (Mostly) Complete Guide to React Rendering Behavior (2020) e suas palestras sobre renderização e sobre o compiladorum modelo preciso de renderização, Context e memo
Dan Abramov, Before You memo() (overreacted.io)as duas técnicas estruturais e a ideia de identidade de elementos por trás delas
TkDodo, The uphill battle of memoizationpor que a memoização manual é frágil e a alternativa dos stores externos
Documentação do TanStack Query, "Performance & Request Waterfalls"como as cascatas se formam e como removê-las
MDN, Closuresa semântica de JavaScript por baixo do estado obsoleto
Nadia Makarevich, Advanced React (2023, advanced-react.com)uma investigação do tamanho de um livro, guiada por exemplos, sobre re-renderizações, memoização, reconciliação, Context, refs, closures, portais, busca de dados, condições de corrida e tratamento de erros; escrito para o React 18, então leia as mudanças deste guia ao lado dele

14. Erros comuns

15. O que mencionar em uma entrevista

Resumo rápido

Apêndice: o código dos experimentos

Os quatro scripts usam apenas Node.js 22 (sem pacotes) e modelam a mecânica de JavaScript por trás dos temas; nenhum deles executa React nem um navegador. O formula.js confere a probabilidade de corrida em forma fechada citada na seção 10, e o waterfall.js confere a sua aritmética. O race.js e o closures.js demonstram mecanismos; os números deles dependem dos parâmetros no início de cada script, então mude-os, e o guia não os cita como resultados. O race.js usa sementes fixas, de modo que as suas contagens se repetem de uma execução para outra; os tempos do waterfall.js variam alguns milissegundos.

formula.js: a probabilidade da corrida, conferida

Execute com node formula.js; leva um ou dois segundos. Ele compara a forma fechada da seção 10 com sorteios aleatórios.

// Two requests started `gap` ms apart; each response time is uniform between 0 and `width` ms, independent of the other.
// The bug: the OLDER request's response arrives after the NEWER one's, so a naive effect shows the older data last.
function simulate(width, gap, rounds = 1_000_000) {
  let wrong = 0;
  for (let i = 0; i < rounds; i++) {
    const older = Math.random() * width;      // response time of the first request
    const newer = Math.random() * width;       // response time of the second request, which started `gap` ms later
    if (gap + newer < older) wrong++;          // the newer response arrived first
  }
  return wrong / rounds;
}
const formula = (width, gap) => (gap < width ? 0.5 * (1 - gap / width) ** 2 : 0);

for (const [width, gap] of [[40, 10], [200, 10], [200, 50], [200, 150], [40, 50]]) {
  console.log(`w=${width} g=${gap}: formula ${(100 * formula(width, gap)).toFixed(1)}%  simulated ${(100 * simulate(width, gap)).toFixed(1)}%`);
}

race.js: respostas fora de ordem e quatro estratégias

Execute com node race.js; leva cerca de vinte segundos porque repete o experimento com várias sementes, temporizações e taxas de falha.

// Out-of-order responses: the mechanics behind a data-fetching race in an effect. Plain Node.js 22, no React.
// This demonstrates a mechanism. It is NOT an estimate of how often the bug happens in production: every number below depends
// on the delay range, the spacing between requests and the failure rate chosen here. Change them and watch the numbers move.
// Each "render" starts a request for its own id (page 1, 2, 3). The outcome of the LAST request started (data, or an error if
// that request failed) is the correct final state of the screen.
function makeRng(seed) { let s = seed >>> 0; return () => ((s = (Math.imul(s, 1664525) + 1013904223) >>> 0) / 4294967296); }
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

// One round: three requests started gapMs apart, with delays and failures fixed by `plan` so every strategy sees the same rounds.
async function round(strategy, plan, gapMs) {
  let screen = null, latest = 0, staleWrites = 0;
  const cleanups = [], pending = [];
  const fakeFetch = (id, signal) => new Promise((resolve, reject) => {
    const { ms, fail } = plan[id - 1];
    const t = setTimeout(() => (fail ? reject(new Error('network error')) : resolve('data ' + id)), ms);
    signal?.addEventListener('abort', () => { clearTimeout(t); reject(new DOMException('aborted', 'AbortError')); });
  });
  for (let id = 1; id <= 3; id++) {
    latest = id;
    cleanups.splice(0).forEach((f) => f());                  // React runs the previous effect's cleanup first
    let ignore = false; const ac = new AbortController();
    if (strategy === 'ignore-flag') cleanups.push(() => { ignore = true; });
    if (strategy === 'abort') cleanups.push(() => ac.abort());
    const apply = (value) => {
      if (strategy === 'ignore-flag' && ignore) return;
      if (strategy === 'compare-id' && id !== latest) return;
      screen = value;
      if (id !== latest) staleWrites++;                      // an out-of-date result was written to the screen
    };
    pending.push(fakeFetch(id, strategy === 'abort' ? ac.signal : undefined)
      .then(apply, (e) => { if (e.name !== 'AbortError') apply('error ' + id); }));
    await sleep(gapMs);
  }
  await Promise.all(pending);
  const expected = plan[2].fail ? 'error 3' : 'data 3';
  return { wrong: screen !== expected, staleWrites };
}
async function run(strategy, cfg, seed, rounds) {
  const rnd = makeRng(seed);
  const plans = Array.from({ length: rounds }, () => [1, 2, 3].map(() => ({
    ms: cfg.minMs + Math.floor(rnd() * (cfg.maxMs - cfg.minMs + 1)), fail: rnd() < cfg.failRate })));
  const out = await Promise.all(plans.map((p) => round(strategy, p, cfg.gapMs)));   // rounds are independent, so run them side by side
  return { wrong: out.filter((x) => x.wrong).length, stale: out.reduce((a, x) => a + x.staleWrites, 0) };
}
const strategies = ['naive', 'ignore-flag', 'compare-id', 'abort'];
const base = { minMs: 5, maxMs: 45, gapMs: 10, failRate: 0 };
const SEEDS = [1, 2, 3, 4, 5];
(async () => {
  console.log('A. Five seeds, 400 rounds each (delays 5-45 ms, requests 10 ms apart, no failures): rounds ending with the wrong screen');
  for (const s of strategies) {
    const w = []; for (const seed of SEEDS) w.push((await run(s, base, seed, 400)).wrong);
    console.log('  ' + s.padEnd(12), 'min ' + String(Math.min(...w)).padStart(3), ' max ' + String(Math.max(...w)).padStart(3), ' [' + w.join(', ') + ']');
  }
  console.log('B. Naive strategy, varying the delay range and the spacing between requests (no failures): % of rounds ending wrong (5 seeds x 200 rounds)');
  for (const [lo, hi] of [[5, 15], [5, 45], [5, 205]]) {
    const row = [];
    for (const gap of [10, 50, 150]) {
      let w = 0; for (const seed of SEEDS) w += (await run('naive', { ...base, minMs: lo, maxMs: hi, gapMs: gap }, seed, 200)).wrong;
      row.push((w / 10).toFixed(1).padStart(5) + '%');
    }
    console.log('  delays ' + (lo + '-' + hi + ' ms').padEnd(9), 'spacing 10 / 50 / 150 ms:', row.join('  '));
  }
  console.log('C. Failure rate (delays 5-45 ms, 10 ms apart): % of rounds ending wrong (5 seeds x 200 rounds)');
  for (const f of [0, 0.05, 0.2]) {
    const row = [];
    for (const s of strategies) { let w = 0; for (const seed of SEEDS) w += (await run(s, { ...base, failRate: f }, seed, 200)).wrong; row.push(s + ' ' + (w / 10).toFixed(1) + '%'); }
    console.log('  failures ' + String(Math.round(f * 100)).padStart(2) + '%:', row.join('  |  '));
  }
})();

waterfall.js: requisições sequenciais e paralelas contra um servidor local

Execute com node waterfall.js; cada célula é a mediana de sete execuções.

// Request waterfalls and a per-host connection limit, modelled with a local HTTP/1.1 server (Node 22, no React, no browser).
// This demonstrates a mechanism. It is NOT a prediction for production: a real page adds DNS, TLS, caching, HTTP/2 multiplexing,
// server-side variation and rendering time. What carries over is the shape: a chain of N dependent requests costs about N x latency,
// independent requests started together cost about 1 x latency, and a connection limit adds one extra "round" per batch of requests.
// Every endpoint answers after a fixed delay. Each measurement is repeated and we report the median and the range.
const http = require('http');
const server = http.createServer((req, res) => {
  const ms = Number(new URL(req.url, 'http://x').searchParams.get('ms') || 100);
  setTimeout(() => { res.end(JSON.stringify({ path: req.url })); }, ms);
});
const get = (agent, path, ms) => new Promise((resolve, reject) => {
  http.get({ port: server.address().port, path: `${path}?ms=${ms}`, agent }, (r) => { r.resume(); r.on('end', resolve); }).on('error', reject);
});
const time = async (f) => { const t = performance.now(); await f(); return Math.round(performance.now() - t); };
const stat = (xs) => { const s = [...xs].sort((a, b) => a - b); return `${s[Math.floor(s.length / 2)]} ms (${s[0]}-${s[s.length - 1]})`; };
const REPEATS = 7;
server.listen(0, async () => {
  const keep = (n) => new http.Agent({ keepAlive: true, maxSockets: n });
  const warm = async (a, n) => { await Promise.all(Array.from({ length: n }, (_, i) => get(a, '/warm' + i, 1))); };   // open the connections first
  const measure = async (f) => { const xs = []; for (let i = 0; i < REPEATS; i++) xs.push(await time(f)); return stat(xs); };
  console.log(`Median and range of ${REPEATS} runs.`);
  console.log('A. Three requests, by latency per request');
  for (const L of [20, 100, 300]) {
    const a = keep(6); await warm(a, 6);
    const dep = await measure(async () => { await get(a, '/user', L); await get(a, '/posts', L); await get(a, '/comments', L); });
    const par = await measure(() => Promise.all([get(a, '/user', L), get(a, '/posts', L), get(a, '/comments', L)]));
    const one = await measure(() => get(a, '/user-with-posts-and-comments', L));
    console.log(`  latency ${String(L).padStart(3)} ms | dependent chain ${dep.padEnd(18)} | started together ${par.padEnd(18)} | one combined endpoint ${one}`);
    a.destroy();
  }
  console.log('B. Twelve independent requests at 100 ms each, by the number of connections allowed');
  for (const n of [1, 2, 6, 12]) {
    const a = keep(n); await warm(a, n);
    console.log(`  ${String(n).padStart(2)} connection${n === 1 ? ' ' : 's'} | ${await measure(() => Promise.all(Array.from({ length: 12 }, (_, i) => get(a, '/r' + i, 100))))}`);
    a.destroy();
  }
  server.close();
});

closures.js: closures obsoletas e três formas de aplicar debounce

Execute com node closures.js.

// The JavaScript mechanics behind stale closures and debouncing in components. Plain Node.js 22; NOT React.
// A "render" is a function call that receives the current state; anything created inside it closes over THAT render's state.
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

function debounce(fn, ms) { let t; return (...a) => { clearTimeout(t); t = setTimeout(() => fn(...a), ms); }; }

(async () => {
  // ---- 1. Stale closure: a callback created in render 1 and kept ("effect with empty dependencies") ----
  const slots = { latest: { current: 0 } };                    // a ref: one mutable object that survives across renders
  const seen = { stale: [], viaRef: [], recreated: [] };
  let recreatedTimer;
  const render = (count, first) => {
    slots.latest.current = count;                              // "update the ref after each render"
    if (first) {
      setInterval(() => seen.stale.push(count), 20);           // closure over render 1's count, never replaced
      setInterval(() => seen.viaRef.push(slots.latest.current), 20);   // reads the mutable ref: always the newest
    }
    clearInterval(recreatedTimer);                             // "dependencies changed: clean up and create again"
    recreatedTimer = setInterval(() => seen.recreated.push(count), 20);
  };
  render(0, true); await sleep(100);
  render(1, false); await sleep(100);
  for (const k in seen) seen[k].length = 0;                    // look only at what happens after the last render
  render(2, false); await sleep(100);
  process.stdout.write('1. values seen by a 20 ms timer after the last render (count went 0 -> 1 -> 2)\n');
  for (const [k, v] of Object.entries(seen)) console.log('   ' + k.padEnd(10), [...new Set(v)].join(','));
  // ---- 2. Debounce created in three ways; the user types "r", "re", "rea", "reac", "react" 10 ms apart ----
  const typed = ['r', 're', 'rea', 'reac', 'react'];
  async function scenario(kind) {
    const calls = [];
    const search = (q) => calls.push(q);
    let kept;                                                  // what a hook would keep between renders
    const latestSearch = { current: search };
    const renderInput = (text) => {
      latestSearch.current = () => search(text);               // new function each render, sees this render's text
      if (kind === 'recreated-in-render') return debounce(() => search(text), 50);       // new timer every render
      if (kind === 'kept-but-stale') { kept ??= debounce(() => search(text), 50); return kept; }   // first render's closure
      if (kind === 'kept-with-ref')  { kept ??= debounce(() => latestSearch.current(), 50); return kept; }
    };
    for (const text of typed) { renderInput(text)(); await sleep(10); }
    await sleep(120);
    return calls;
  }
  console.log('2. searches performed while typing "react" (5 renders, 10 ms apart, 50 ms debounce):');
  for (const k of ['recreated-in-render', 'kept-but-stale', 'kept-with-ref']) console.log('   ' + k.padEnd(20), JSON.stringify(await scenario(k)));
  process.exit(0);
})();

Fontes

Pratique este tema: React

Mais guias