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ê quer | Leia |
|---|---|
| O modelo e as correções em 15 minutos | Comece aqui, as seções 1 e 2, o Resumo rápido |
| Consertar uma tela lenta ou errada | Comece aqui, depois o índice de sintomas, depois a seção que ele indica |
| O quadro completo | Em 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.
| Tipo | Onde | Quanto confiar |
|---|---|---|
| Comportamento documentado | react.dev, MDN, TanStack e as outras fontes citadas no texto | tanto quanto a fonte; confira a versão |
| Raciocínio derivado | a 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 mecanismo | os scripts do apêndice | mostram por que um padrão se comporta assim; os números dependem de parâmetros escolhidos pelo autor |
| Medido em um app real | nenhum | nenhum 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.
| Degrau | Pergunte | Correção típica | O que ela custa | Seção |
|---|---|---|---|---|
| 1. Medir | Está lento para uma pessoa, e em qual interação? | grave uma interação fixa no Profiler; olhe o painel Performance | nada | 4 |
| 2. Remover trabalho pela estrutura | Algo re-renderiza sem depender do que mudou? | mover o estado para baixo; subir o conteúdo como children | uma pequena refatoração, fácil de desfazer | 2 |
| 3. Guardar em cache | Um componente caro re-renderiza com entradas iguais? | o React Compiler; senão memo e useMemo | a estabilidade das props vira sua tarefa; bugs de cache obsoleto | 3 |
| 4. Reordenar | O trabalho é necessário, mas não urgente? | useTransition, useDeferredValue | a tela fica brevemente desatualizada; o trabalho total não diminui | 4 |
| 5. Fazer menos | Simplesmente há coisa demais para renderizar? | virtualização, paginação, content-visibility | busca na página, foco, acessibilidade e posição de rolagem exigem cuidado | 4 |
| 6. Mover | É computação, não renderização? | um Web Worker, ou o servidor | serialização e uma arquitetura mais complexa | 4 |
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 habitual | Primeira correção | Seção |
|---|---|---|---|
| Digitar em um campo trava | o estado está alto demais, acima de uma árvore lenta | mover o estado para baixo, ou subir o conteúdo lento | 2, 4 |
| Uma lista fica lenta a cada mudança | as linhas re-renderizam com dados iguais | compilador ou memo com props estáveis; virtualizar se houver muitíssimas linhas | 3, 4 |
| Um formulário perde o texto ou o foco quando algo atualiza | um componente definido dentro de outro, ou uma key instável | declare-o no nível superior; use chaves estáveis | 5 |
| Depois de reordenar, uma linha fica com o campo de outra | índice do array usado como key | use o id do registro | 5 |
| Uma mudança de contexto re-renderiza metade da página | todo consumidor acompanha toda mudança | divida o contexto, ou use um store com seletores | 6 |
| Um timer ou manipulador registra um valor antigo | closure obsoleta | liste a dependência, use um atualizador ou useEffectEvent | 7 |
| A tela mostra dados de outro item após cliques rápidos | uma resposta mais lenta e mais antiga chegou por último | limpeza com flag de ignorar, ou uma biblioteca de dados | 10 |
| A página se preenche passo a passo | uma cascata de requisições | eleve, faça prefetch ou reestruture as requisições | 10 |
| A tela inteira fica em branco após um erro | não há error boundary | boundaries no nível da página e do widget | 11 |
| Um modal ou tooltip aparece cortado | um ancestral com overflow ou um contexto de empilhamento | um portal, ou o <dialog> nativo | 9 |
| Uma posição pisca depois de medir | medição em useEffect | useLayoutEffect, ou CSS | 9 |
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.
- Um componente é uma função que recebe props e devolve elementos.
- Um elemento é um objeto simples que descreve o que renderizar: um tipo (
'div'ou um componente) e props. Escrever<Child />cria um elemento; não executaChild. - Uma renderização é o React chamando a função do componente. Não é uma atualização da tela.
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:
| Ferramenta | O que mantém | Quando importa |
|---|---|---|
useMemo(fn, deps) | o resultado de fn até que deps mudem | um cálculo caro, ou um valor usado como dependência ou como prop de um componente memoizado |
useCallback(fn, deps) | a própria função | o 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 pai | um 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"):
- 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. - Uma única prop instável derrota o
React.memodo componente inteiro. Objetos, arrays, funções echildrenem JSX escritos inline são referências novas a cada renderização, e um novo valor de reserva comovalue ?? []pode quebrar a estabilidade outra vez. Alguém que adicione uma prop depois pode desfazer o benefício sem perceber. - O
React.memosó impede re-renderizações causadas pelo pai. Uma mudança de estado ou de contexto dentro do componente ainda o renderiza. - 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ção | Orientação do anúncio do React Compiler 1.0 |
|---|---|
| Código novo | confie 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 existente | deixe 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 React | o 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):
- 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.
- A saída do build. O código compilado importa
c as _cdereact/compiler-runtimee guarda os resultados em um array de cache (const $ = _c(1)), então uma busca rápida porcompiler-runtimeno arquivo gerado diz se um arquivo chegou a ser transformado. - Lint. As regras do compilador vêm no
eslint-plugin-react-hooks(o presetrecommended-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. - Eventos de build. A opção
loggerrecebe uma funçãologEvent(filename, event), de modo que um build pode imprimir o que foi compilado (o exemplo da documentação verificaevent.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:
- Eles reordenam o trabalho; não o removem. A renderização total é a mesma, e o tráfego de rede também (um valor adiado não faz debounce de requisições).
- Um único componente lento não pode ser interrompido. O React pode pausar entre componentes, não no meio de um. Se um componente leva 300 ms, uma transição não o torna mais rápido.
- O
useDeferredValueprecisa que o filho lento seja memoizado (commemoou o compilador). Senão o filho renderiza uma vez com o valor antigo e outra com o novo. - Uma transição não pode controlar um campo de texto controlado; o estado do próprio campo deve continuar urgente, como no exemplo.
- Mostre que a tela está atrasada:
isPending, ouquery !== deferredQuery, é o sinal para esmaecer. - Uma transição que suspende mantém a tela antiga em vez de trocar um conteúdo já visível por um fallback.
- React 19: o
startTransitionaceita uma função assíncrona (uma Action), mas uma atualização de estado depois de umawaitnão faz parte da transição; envolva-a no seu própriostartTransition.
Fazer menos. Quando o problema é a própria lista, renderizá-la mais rápido é a alavanca errada; renderize menos linhas.
| Técnica | O que ela remove | O que ela custa |
|---|---|---|
Janelamento (@tanstack/react-virtual, react-window) | trabalho do React e nós do DOM das linhas fora da área visível | a 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 renderizadas | o modelo de navegação muda, mas é o mais simples e o mais acessível |
content-visibility: auto com contain-intrinsic-size | o layout e a pintura do navegador das seções fora da tela | o 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 é mantido | a 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):
| Passo | Mudança | O que a auditoria deve mostrar |
|---|---|---|
| 0 | Gravar: <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) |
| 1 | Estrutura: manter query no componente que precisa dele e subir o resto do conteúdo da tabela como children | o cabeçalho e a barra lateral deixam de aparecer |
| 2 | Cache: compilador, ou memo em Row com props estáveis | as linhas que sobrevivem ao filtro deixam de renderizar; as que aparecem ainda custam |
| 3 | Reordenar: useDeferredValue(query) para a tabela | o campo continua responsivo; a tabela o alcança um instante depois |
| 4 | Fazer menos: janelar as linhas | só as linhas visíveis renderizam, qualquer que seja o tamanho dos dados |
| 5 | Mover: se filtrar 5.000 registros já é lento, filtrar em um worker | o 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:
- O mesmo tipo de componente na mesma posição mantém o seu estado, mesmo que as props mudem;
{isFancy ? <Counter isFancy /> : <Counter />}mantém um único contador. - Um tipo diferente nessa posição (
<Counter />substituído por<p>, ousectionpordiv) destrói a subárvore antiga e o seu estado e monta uma nova. - Uma condicional como
isOpen ? <Panel /> : nullsempre ocupa um espaço. - Em listas dinâmicas, a posição não é uma identidade confiável, então cada item recebe uma
key: um valor estável, único entre os irmãos, que o identifica através de reordenações, inserções e remoções.
Quatro consequências que causam bugs reais:
- 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.
- 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.
- 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. - 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 quandoidmuda. 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:
- Memoize o valor (
useMemo) e as suas funções (useCallback), para que o provider renderizando por um motivo não relacionado não o altere. - Divida os contextos conforme a frequência de mudança: o padrão da documentação do React para combinar um reducer com o contexto usa dois contextos, um para o estado e um para o
dispatch, porque odispatchnunca muda, e assim um componente que só despacha não re-renderiza quando o estado muda. - Passe os filhos pelo provider em vez de criá-los dentro dele, para que ele não os re-renderize (seção 2).
- Para estados maiores ou que mudam mais rápido, use um store fora do React com seletores (Zustand, Redux, Jotai e semelhantes), em que os componentes assinam a fatia que leem. TkDodo defende esse argumento como alternativa a correr atrás da estabilidade das props; o
useSyncExternalStoredo React é a primitiva que esses stores usam, e a documentação o recomenda no lugar de uma assinatura escrita à mão em um efeito.
O que mudou no React 19:
| Antes | Agora |
|---|---|
<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 superior | use(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 Component | desde 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):
| Abordagem | CountView | NameView | ResetButton | Custo e ressalva |
|---|---|---|---|---|
| A. um contexto | sim | sim (lê o mesmo contexto) | sim | o mais simples; todo consumidor acompanha toda mudança |
| B. contextos divididos | sim | não | não (lê só as ações estáveis) | mais providers para escrever e manter na ordem certa |
| C. store com seletores | sim | não | não | uma dependência nova ou um pequeno store para manter; os seletores precisam devolver valores estáveis |
| D. só props | sim | sim, a menos que esteja memoizado ou o seu elemento seja criado acima do dono | sim, 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 é criado | Valor 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ção | 2 |
| recriado sempre que o valor muda (a lista de dependências o inclui) | 2 |
Correções, em ordem de preferência:
- Liste a dependência; a regra
react-hooks/exhaustive-depsa 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. - Use uma atualização funcional (
setCount((c) => c + 1)) para que o valor não seja necessário. - 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 aoroomId, enquanto uma notificação de "conectado" lê othemeatual 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). - Guarde a função mais recente em uma ref e leia
ref.currenta partir do callback de longa duração. É o padrão mais antigo, ainda útil fora dos efeitos; ouseEffectEventagora 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 debounce | Buscas 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ção | 1, com o texto errado: r |
| criada uma vez, chamando a função mais recente por meio de uma ref | 1, 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ório | forwardRef 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ção | Use quando |
|---|---|
trocá-lo por useEffect | o 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 |
useSyncExternalStore | o 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)
| Forma | Tempo | Com 100 ms por requisição (aritmética, não medição) |
|---|---|---|
| n requisições, uma depois da outra | n × L | 3 requisições: 300 ms |
| n requisições iniciadas juntas | L, a mais lenta | 3 requisições: 100 ms |
| n requisições, c conexões por vez | ⌈n / c⌉ × L | 12 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 w | Requisições com g de intervalo | Chance de a resposta mais antiga chegar por último |
|---|---|---|
| 40 ms | 10 ms | 28% |
| 200 ms | 10 ms | 45% |
| 200 ms | 50 ms | 28% |
| 200 ms | 150 ms | 3% |
| 40 ms | 50 ms ou mais | 0% |
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:
- O navegador para de esperar, e a promise do
fetché rejeitada com umAbortError(MDN, AbortController). - A parte não lida da resposta é descartada, e o navegador normalmente fecha a conexão ou reinicia o stream HTTP/2.
- Isso não garante que o servidor pare. Um servidor que já recebeu a requisição pode executar a consulta ou o job até o fim, a menos que perceba a conexão fechada e tenha sido escrito para parar (muitos frameworks de servidor expõem um sinal de requisição encerrada ou de abort, e o seu handler precisa usá-lo).
- Para uma mutação (um POST que paga, envia ou apaga), abortar não desfaz nada: o servidor pode tê-la concluído. Use uma chave de idempotência e leia o estado real depois, em vez de supor que a requisição não aconteceu.
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).
- React 19 e posteriores. O React 19 documenta o
use(promise): um componente lê uma promise durante a renderização, o React suspende o componente, e o<Suspense fallback={...}>mais próximo é exibido até ela resolver. Uma promise rejeitada vira um erro para o error boundary mais próximo. Materiais antigos que chamam o Suspense para dados de "não suportado" são anteriores a isso. - A promise não pode ser criada durante a renderização que a lê: uma promise nova a cada renderização nunca se resolveria, e o React avisa. Ela deve vir de um cache, biblioteca ou framework compatível com o Suspense (um loader, um Server Component pai ou uma promise mantida em um cache). Por isso o conselho acima, de usar uma biblioteca ou um framework, continua valendo.
- O React 19.0 também adicionou o pre-warming: quando um componente suspende, o React faz o commit do fallback mais próximo de imediato e continua renderizando os irmãos para iniciar cedo as suas requisições, o que reduz algumas cascatas.
- Para alterações, o React 19 adiciona as Actions: funções assíncronas usadas em transições que acompanham um estado de pendente, erros e o reset do formulário, com
<form action={fn}>,useActionState([state, formAction, isPending]),useFormStatuseuseOptimistic. Elas substituem muito do código escrito à mão de "isLoading, error, setData" em formulários e mutações. - O Suspense substitui o malabarismo com flags de carregamento; não remove as cascatas causadas pela busca em componentes aninhados, nem a necessidade de cache.
// 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:
| Ferramenta | Captura | Não captura |
|---|---|---|
| error boundary | erros lançados durante a renderização dos componentes abaixo dele, por mais fundo que estejam | erros 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/catch | erros em manipuladores de evento, callbacks e código com await | erros 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>
);
}
| Passo | O que acontece | Quem trata |
|---|---|---|
| 1. A requisição falha | a 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 captura | o error boundary |
| 3. Logging | o 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. Fallback | o boundary renderiza a mensagem e o botão; o resto da página continua funcionando | o boundary |
| 5. Nova tentativa e recuperação | o 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 fallback | a 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ão | Data | O que importa para este guia |
|---|---|---|
| React 19.0 | 5 dez 2024 | ref como prop; limpeza de ref; use(); Actions, useActionState, useOptimistic, useFormStatus; <Context value>; onCaughtError e onUncaughtError; pre-warming do Suspense |
| React 19.2 | 1 out 2025 | useEffectEvent; <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.0 | 7 out 2025 | memoização automática (seção 3) |
| React 19.3 | 9 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:
| Recurso | Exige | Tipo |
|---|---|---|
Hooks, createContext, React.memo, useLayoutEffect, portais, error boundaries (de classe), AbortController em efeitos | React 16.8 ou posterior (portais 16.0; error boundaries 16.0) | núcleo estável |
useSyncExternalStore, useDeferredValue, transições | React 18 ou posterior | núcleo estável |
ref como prop, <Ctx value>, use(), Actions, useActionState, useOptimistic, onCaughtError | React 19.0 ou posterior | núcleo estável; não existe no React 18 |
useEffectEvent, <Activity> | React 19.2 ou posterior | núcleo estável; não existe no React 19.0 nem no 19.1 |
use(browser()), <ViewTransition>, refs em Fragment | React 19.3 | núcleo estável, a versão mais recente |
| React Compiler | o seu próprio pacote, babel-plugin-react-compiler, instalado no build | uma ferramenta de build, não parte do pacote react; suporta o React 17 e superiores |
| Server Components, Server Functions | um 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, Zustand | as versões da própria biblioteca | bibliotecas 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:
| Fonte | Boa 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 Component | as 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 compilador | um 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 memoization | por 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, Closures | a 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
- Memoizar as props de um componente que nada compara, ou envolver tudo em
React.memopassando a cada renderização um objeto, uma função ouchildrennovos. - Definir um componente dentro de outro componente, perdendo o seu estado a cada renderização.
- Usar o índice ou um valor aleatório como
key. - Colocar um valor que muda com frequência em um único Context grande, lido por tudo.
- Chamar
fetchem um efeito sem limpeza, de modo que uma resposta antiga e mais lenta vence. - Supor que o
AbortControllerpara o servidor ou desfaz uma requisição que já chegou a ele. - Citar um número de uma demonstração, ou do app de outra pessoa, como se descrevesse o seu; registre o seu.
- Recorrer à virtualização ou a uma transição antes de medir e de reestruturar.
- Esperar que o
useDeferredValueajude um filho que não é memoizado, ou que ouseTransitionacelere um único componente lento. - Supor que o compilador otimizou um componente sem verificar o selo ou a saída do lint.
- Usar o Context para estado que muda rápido, ou memoizar o valor do provider como substituto de decidir quem é dono do estado.
- Iniciar requisições dependentes a partir de componentes aninhados, de modo que rodam uma depois da outra.
- Deixar uma dependência fora de um efeito para "fazê-lo rodar uma vez" e depois ler valores obsoletos.
- Criar uma função com debounce no corpo da renderização.
- Ler ou escrever
ref.currentdurante a renderização. - Usar
useLayoutEffectpara algo que não precisa bloquear a pintura, ou no servidor sem um plano. - Esperar que um error boundary capture um erro lançado em um manipulador de evento ou em uma promise.
- Escrever novos wrappers com
forwardRef, ou memoizar tudo à mão em um código que já usa o compilador. - Copiar um tutorial sem verificar a qual versão do React ele se destina.
15. O que mencionar em uma entrevista
- "Uma renderização é a chamada da função do componente. Ela roda de novo quando o seu estado ou um contexto que ela lê muda, ou quando o pai renderiza, e então os filhos rodam de novo por padrão, a menos que algo o impeça: os seus elementos são os mesmos objetos, eles estão memoizados ou o compilador os memoizou. Eu confiro o Profiler em vez de supor."
- Estrutura antes do cache: mover o estado para baixo, passar o conteúdo como
children;memo,useMemoeuseCallbackguardam em cache e precisam de props estáveis; o compilador agora faz boa parte disso. - O estado segue a posição na árvore;
keydá identidade em listas e pode redefinir o estado; um componente definido dentro de outro é remontado a cada renderização. - O Context re-renderiza todos os consumidores a qualquer mudança de valor; divida-o, memoize o valor ou use um store com seletores.
- Refs são caixas mutáveis que não re-renderizam; no React 19,
refé uma prop e oforwardRefestá de saída. - Closures obsoletas: a lista de dependências, atualizações funcionais,
useEffectEvente o padrão da ref com o valor mais recente. - Respostas fora de ordem se resolvem, quanto à correção, com uma limpeza com flag de ignorar ou uma comparação de id da requisição; o
AbortControllertambém cancela no cliente, mas não faz o servidor parar e não desfaz uma mutação. Uma biblioteca esconde tudo isso. - As cascatas vêm de busca aninhada ou dependente; inicie as requisições independentes juntas e cedo, ou leve-as ao servidor.
- Quando ainda está lento: meça, depois estrutura, cache, reordenar (
useTransition,useDeferredValue: o mesmo trabalho, mais tarde, interrompível entre componentes), fazer menos (janelamento, paginação) e tirar a computação da thread principal. Diga o custo de cada passo. - Error boundaries capturam apenas erros de renderização; os erros assíncronos precisam de
try/catch, e de um relançamento na renderização só quando se quer o fallback inteiro; uma configuração completa também registra o erro e oferece uma nova tentativa; o React 19 adicionaonCaughtErroreonUncaughtError. - O que mudou: o Compiler,
use(), Actions,useEffectEvent,<Activity>e os patches de segurança dos Server Components.
Resumo rápido
- Uma renderização é uma chamada de função, não uma atualização da tela; por padrão os pais re-renderizam os filhos, a menos que algo o impeça, e as props não são o que a dispara.
- Reestruture primeiro, memoize depois, e deixe o React Compiler fazer a memoização rotineira em código novo. Se ainda estiver lento, reordene (transições), faça menos (janelamento) ou tire o trabalho da thread principal, nessa ordem, e meça cada passo.
- O estado segue a posição; as chaves dão identidade e podem redefinir o estado; nunca defina componentes dentro de componentes.
- O Context re-renderiza todos os consumidores; divida-o ou use um store com seletores.
- Closures são fotografias: corrija dados obsoletos com dependências, atualizadores,
useEffectEventou uma ref com o valor mais recente. - As refs são mutáveis e silenciosas;
refé uma prop no React 19. - Busque dados com limpeza, em paralelo onde as requisições são independentes (as dependentes precisam de reestruturação, não de
Promise.all), por meio de uma biblioteca ou de um framework; ouse()precisa de uma promise vinda de um cache, não de uma criada na renderização. - Error boundaries para erros de renderização, com logging e uma nova tentativa;
try/catchpara os assíncronos; relatório no nível da raiz. - Mantenha o React e os seus pacotes de servidor atualizados e leia mais de uma fonte.
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
- React team, Preserving and Resetting State, You Might Not Need an Effect, Separating Events from Effects, Scaling Up with Reducer and Context, e as referências de
createPortal,useLayoutEffect,forwardRefeComponent(error boundaries). - React team, React v19, o React 19 Upgrade Guide, React 19.2, React 19.3, React Compiler v1.0 e React Versions.
- React team, Critical Security Vulnerability in React Server Components (CVE-2025-55182, versões afetadas e corrigidas).
- Mark Erikson, A (Mostly) Complete Guide to React Rendering Behavior, e A Guide to React Compiler Rendering.
- Dan Abramov, Before You memo().
- TkDodo, The uphill battle of memoization.
- TanStack Query, Performance & Request Waterfalls.
- MDN, Closures, e AbortController.
- React team, React Compiler: installation, configuration e a referência de
use. - Brian Vaughn, react-error-boundary (
ErrorBoundary,resetKeys,useErrorBoundary). - Nadia Makarevich, Advanced React (2023), um tratamento do tamanho de um livro de vários temas das seções 2 a 11; veja a seção 13.
Pratique este tema: React