Passada de desempenho
O Data Client pode deixar um app mais rápido do que uma migração simples mostra. Execute esta passada depois de uma migração, ou a qualquer momento em um app que já use o Data Client.
Uma migração já deve entregar os ganhos embutidos: eles exigem pouco código e corrigem comportamentos desatualizados ou lentos, então verifique se estão no lugar e corrija os que estiverem faltando. As mudanças com contrapartidas exigem código extra ou mudam o que os usuários veem, como quando um estado de carregamento aparece ou quando uma mudança surge. Elas formam uma etapa separada e opcional: faça-as uma de cada vez, mantenha os testes passando e pule as que você não quiser.
Meça primeiro
Registre uma linha de base antes de mudar qualquer coisa e meça de novo após cada mudança:
- Requisições: no painel Network do navegador, conte as leituras em cada navegação e após cada mutação.
- Tempo até atualizar: no painel Performance, o tempo entre um clique e a tela mostrar seu resultado, não apenas a próxima pintura. Limite a CPU e adicione latência de rede para que os números se pareçam com os de dispositivos reais.
- Renderizações: o Profiler do React DevTools mostra quais componentes renderizam após uma atualização.
Sem um navegador, conte as requisições que cada fluxo faz a partir do código e dos seus testes, e diga como você contou.
Ganhos embutidos
Detalhes a partir de listas
Um endpoint de detalhe cujo schema contém a Entity da lista renderiza um item que a lista já carregou,
sem fetch, enquanto esses dados estiverem atualizados. A busca usa os args do endpoint, então eles devem usar o nome de campo que o
pk() da Entity lê ({ id }, não { issueId }), ou um campo em seus indexes.
- Encontre: endpoints de detalhe sem schema, ou com um schema que deixa a Entity de fora; args de detalhe que não nomeiam
nem a chave primária nem um index (
{ slug }semstatic indexes = ['slug']); dados da lista copiados para o detalhe à mão. - Mude: defina o schema do detalhe como a Entity, ou como um objeto que a contenha, como
{ data: Issue }. Para outros campos de busca, adicione um index em vez de renomear os args. Apague a cópia. Quando a lista retorna menos campos que o detalhe, dê à lista uma Entity de resumo, e faça a Entity do detalhe estendê-la com a mesmakeye umvalidate(), para que o detalhe ainda busque o item completo (entities parciais). - Os usuários veem: a página de detalhe aparece na hora quando aberta a partir da lista. Ela não faz nenhuma requisição enquanto a lista estiver atualizada e tiver todos os campos que o detalhe exige.
Uma Entity em todo lugar
Todo lugar que mostra um objeto do servidor lê a mesma Entity, então uma resposta atualiza todos eles.
- Encontre: campos de Entity que contêm objetos com id próprio mas sem uma entrada em
static schema; duas classes Entity com keys diferentes para o mesmo objeto do servidor (uma Entity de resumo que a Entity de detalhe estende com a mesmakeynão tem problema); endpoints de atualização sem schema;ctrl.expireAll(),ctrl.invalidate()ou um refetch após uma atualização. - Mude: aninhe a Entity em
static schema({ author: User, labels: [Label] }), dê aos endpoints de atualização a Entity como schema e apague o refetch. - Os usuários veem: uma edição aparece em toda linha, card e detalhe de uma vez, sem requisição.
Mutações atualizam listas no lugar
- Encontre:
ctrl.expireAll(),ctrl.invalidate()ou um refetch de uma lista após uma criação, uma exclusão ou uma mudança que move um item entre listas filtradas. - Mude: crie por meio do endpoint
pushouunshiftda Collection da lista; exclua comresource().deleteou um schema Invalidate; mova com o endpointmoveda Collection. MantenhaexpireAll()para páginas numeradas, cujos itens posteriores se deslocam; para listas cuja ordem ou composição o servidor decide; e para dados que a resposta não inclui, como contagens e totais. - Os usuários veem: o item novo, removido ou movido aparece sem recarregar a lista.
Leituras ignoram dados atualizados
- Encontre:
useEffect()que faz fetch;ctrl.fetch()de um endpoint de leitura em loaders de rota ou handlers de prefetch. - Mude: os componentes leem com
useSuspense()ou useFetch(). Apenas o código em que hooks não podem rodar, como loaders de rota e prefetch ao passar o mouse, chamactrl.fetchIfStale().ctrl.fetch()sempre faz a requisição, mesmo quando o store tem dados atualizados, então use-o apenas onde o usuário pede uma atualização. - Os usuários veem: nenhuma mudança; menos requisições por navegação.
Mudanças com contrapartidas
Loaders não esperam por dados secundários
Um loader de roteador que aguarda todas as requisições faz a página esperar pela mais lenta, mesmo quando o item principal veio
da lista. Em um roteador que muda a rota em uma transition, inicie cada fetchIfStale() sem aguardá-lo: a página
renderiza o que está em cache e suspende pelo restante, mantendo a página atual nesse meio-tempo. Dê a cada componente que lê
dados secundários o seu próprio AsyncBoundary, para que carregue sem segurar a página. Quando a página
renderiza o valor de retorno do loader, retorne apenas o item principal, como mostram os Route loaders.
export const issueLoader =
(ctrl: Controller) =>
({ params }: { params: { issueId?: string } }) => {
const id = Number(params.issueId);
return Promise.all([
ctrl.fetchIfStale(IssueResource.get, { id }),
ctrl.fetchIfStale(getNotes, { issueId: id }),
]);
};
export const issueLoader =
(ctrl: Controller) =>
({ params }: { params: { issueId?: string } }) => {
const id = Number(params.issueId);
ctrl.fetchIfStale(IssueResource.get, { id }); // ①
ctrl.fetchIfStale(getNotes, { issueId: id }); // ②
return null;
};
- ①Not awaited: the route changes at once, and the page suspends inside the transition until the issue arrives.
- ②IssueNotes suspends inside its own boundary, which also shows a failure.
import { AsyncBoundary } from '@data-client/react';
import IssueDetail from './IssueDetail';
import IssueNotes from './IssueNotes';
import Spinner from './Spinner';
export default function IssuePage({ id }: { id: number }) {
return (
<>
<IssueDetail id={id} />
<AsyncBoundary fallback={<Spinner />}>
<IssueNotes issueId={id} />
</AsyncBoundary>
</>
);
}
- Encontre: loaders que usam
awaitouPromise.all()em várias requisições; componentes que chamamuseSuspense()abaixo do conteúdo principal da página sem um boundary próprio. - Os usuários veem: a página aparece enquanto as partes secundárias mostram o seu próprio estado de carregamento.
Prefetch por intenção
- Encontre: links para páginas cujos dados o store ainda não tem, em rotas sem loader.
- Mude: chame
ctrl.fetchIfStale(endpoint, args)noonMouseEntere noonFocusdo link, ou adicione um loader. - Os usuários veem: a página aparece sem estado de carregamento. Links sobre os quais se passa o mouse, mas que não são clicados, custam uma requisição.
A expiração se ajusta aos dados
O Data Client refaz o fetch de dados mais antigos que o dataExpiryLength do seu endpoint
(60 segundos por padrão) quando um componente os lê em seguida. Mutações que atualizam o store no lugar mantêm os dados corretos
entre os fetches, então a maioria dos dados pode permanecer atualizada por mais tempo.
- Encontre:
dataExpiryLength: 0, expiração muito curta ouinvalidIfStale: truecopiados de umstaleTime: 0do TanStack Query; dados que raramente mudam, como o usuário atual, configurações ou listas de opções, deixados no padrão. - Mude: remova essas sobrescritas e aumente o
dataExpiryLengthnos endpoints cujos dados mudam apenas por meio deste app. - Os usuários veem: menos refetches em segundo plano e nenhum estado de carregamento ao voltar a uma página. Mudanças feitas em outro lugar aparecem mais tarde.
Atualizações otimistas
Quando o cliente consegue prever o resultado de uma mutação, mostre-o na hora e deixe o Data Client fazer o rollback se a requisição falhar.
Use getOptimisticResponse() no endpoint, ou optimistic: true em
resource(). optimistic: true cobre toda mutação, incluindo criações. Até o servidor
responder, um novo item é armazenado sob uma key temporária aleatória, mas seu id e pk() mantêm o padrão da Entity (como
0), então use outra coisa como key da sua linha e desabilite as outras mutações dele; para tornar uma mutação otimista, adicione
getOptimisticResponse apenas a esse endpoint com resource().extend('partialUpdate', { ... }).
- Encontre:
ctrl.fetch()de atualizações, exclusões e criações cuja resposta o cliente consegue prever a partir do corpo e do store. - Os usuários veem: as mudanças aparecem no clique. Uma requisição com falha reverte a mudança, então continue mostrando o erro.
Visões derivadas em Query
- Encontre: ordenação, filtragem ou agrupamento de dados buscados na renderização ou em
useMemo(). - Mude: faça de uma Query o schema do endpoint e continue lendo com
useSuspense()(ordenação no cliente). Seu resultado é memoizado entre componentes e é recalculado apenas quando suas entradas mudam. O useQuery() nunca faz fetch, então use-o apenas onde os dados já foram buscados em outro lugar. - Os usuários veem: nenhuma mudança; as atualizações renderizam mais rápido em listas grandes.
Leituras em paralelo
- Encontre: duas chamadas a
useSuspense()em um componente em que nenhuma precisa dos dados da outra; um filho que só inicia seu fetch depois que os dados do pai chegam. - Mude: inicie ambas com useFetch() e leia-as com
use(), ou inicie o fetch do filho no loader de rota. Abaixo do React 19, que não temuse(), chameuseFetch()para cada endpoint e depoisuseSuspense()para cada um; as leituras reutilizam as requisições já em andamento. - Os usuários veem: a página carrega mais cedo.
Mantenha os dados atuais durante mudanças
- Encontre: paginação, filtros ou busca que fazem um fallback de carregamento piscar.
- Mude: altere os args dentro de
startTransition(), ou use useDebounce() para texto digitado. - Os usuários veem: os resultados atuais permanecem até os próximos ficarem prontos.
Referências estáveis
O Data Client mantém o objeto de cada Entity o mesmo até que ele mude, então componentes memoizados e o React Compiler pulam as linhas que não mudaram.
- Encontre: entities copiadas ou remodeladas na renderização (
{ ...issue },issues.map(toViewModel)) antes de irem para componentes filhos. - Mude: passe a própria Entity; coloque os campos calculados na classe da Entity como getters.
- Os usuários veem: nenhuma mudança; menos componentes renderizam após cada atualização.
React 19 e React Compiler
O React Compiler memoiza componentes e hooks em tempo de build. Com as referências estáveis acima, menos componentes renderizam após uma atualização do store.
- Encontre:
reactabaixo do 19 no package.json; nenhumbabel-plugin-react-compilerno build (configuração do Babel ou do Vite,reactCompilerna configuração do Next.js, ouexperiments.reactCompilerno app.json do Expo). - Mudança no React 19: siga o guia de instalação e ative
as regras recomendadas do
eslint-plugin-react-hooks. O compiler pula componentes que quebram as Regras do React, e as regras do lint os apontam. Deixe a memoização existente no lugar e execute os testes. - Abaixo do React 19: atualizar o React é um projeto à parte, então não o faça nesta passada. Explique o que o React 19 traz
para este app:
use()para as leituras em paralelo acima e, no 19.2,<Activity>para manter o estado e a saída renderizada de páginas ocultas. Depois pergunte se deve atualizar como um acompanhamento, com o guia de atualização, e ofereça-se para adicionar o compiler junto. O compiler também roda no React 17 e 18 comreact-compiler-runtime; adicione-o antes da atualização apenas se o usuário pedir. - Até a atualização: envolva linhas de lista caras em
memo(), para que as linhas cuja Entity não mudou pulem a renderização. - Os usuários veem: nenhuma mudança. O JavaScript compilado é maior, então meça também o tempo de carregamento.
Relatório
Para cada seção, registre o que você encontrou, o que mudou ou pulou e por quê, e os números de antes e depois.