O original em inglês mudou depois desta tradução, então ela pode estar desatualizada.
Migrando do TanStack Query
O TanStack Query (React Query) guarda em cache a resposta de cada query key separadamente, então o app as mantém consistentes invalidando keys após cada mutação. O Reactive Data Client normaliza as respostas em Entities: a resposta de uma mutação atualiza toda lista e todo detalhe que mostra aquela entity, e a maior parte do código de invalidação desaparece.
A migração substitui as funções e keys de query por endpoints tipados, os hooks por useSuspense()
e chamadas ao Controller, e o QueryClient por DataProvider.
Passos dá a ordem; o mapa de APIs dá a substituição de cada API do TanStack Query.
Migre com o seu agent de código
Cole isto no chat do seu agent:
A skill de configuração segue este guia. Revise o diff dela como o de um colega de equipe.
Passos
Mantenha os testes do app passando após cada passo; eles são a prova de que o comportamento não mudou.
- Endpoints e schemas. Transforme cada função de query e de mutação em um endpoint: siga a
configuração do REST para a biblioteca HTTP que as funções chamam (axios, fetch, ky) e depois dê a cada endpoint um
schemaconstruído a partir de Entities. Sem um schema nada é normalizado, e você precisará manter todas as chamadas ainvalidateQueries. Coloque as Entities e os endpoints em uma pasta que toda feature possa importar (comosrc/resources/), não na pastaapi/de cada feature, mesmo quando os hooks de query ficavam lá: uma mutação em uma feature costuma atualizar a Entity de outra feature. Se regras de lint restringem imports entre pastas (import/no-restricted-paths,eslint-plugin-boundaries, limites de módulo do Nx), use uma camada compartilhada que elas permitam. - Provider. Substitua
QueryClientProviderporDataProvider(Provider). - Leituras. Substitua
useQuery()euseSuspenseQuery()poruseSuspense()no componente que renderiza os dados (Leituras). - Mutações. Substitua
useMutation()porctrl.fetch()e apague a invalidação que a normalização torna desnecessária (Mutações). - Loaders e prefetching. Substitua o
queryClientem loaders de roteador e no prefetching ao passar o mouse porctrl.fetchIfStale()(Loaders e prefetching). - Infinite queries. Substitua
useInfiniteQuery()por uma Collection egetPage(Infinite queries). - Auth. Substitua bibliotecas de autenticação construídas sobre o TanStack Query, como
react-query-auth(Auth). - Testes. Substitua
QueryClientProvidernos wrappers de teste e as suposições sobre spinners de carregamento (Testes). - Limpeza. Apague as fábricas de query keys, os helpers
queryOptions()e configurações no estilolib/react-query.ts. Desinstale@tanstack/react-querye@tanstack/react-query-devtoolsquando nenhum arquivo os importar.
Estes passos mantêm o comportamento do app, exceto onde o Data Client o corrige com menos código: listas que mostravam dados desatualizados depois de uma mutação, refetches depois de uma mutação e fetches de itens que uma lista já carregou. Mudanças que exigem código extra ou alteram o que os usuários veem, como adicionar atualizações otimistas que o app não tinha, são uma passada de desempenho separada e opcional. Termine e verifique primeiro a migração, para poder medir cada etapa.
Mapa de APIs
| TanStack Query | Data Client |
|---|---|
queryFn + queryKey, queryOptions() | Um endpoint com um schema. O endpoint e seus args são a key, então as fábricas de keys desaparecem |
useQuery(), useSuspenseQuery() | useSuspense(endpoint, args): o carregamento vai para o <Suspense> mais próximo, os erros para o error boundary mais próximo, e data nunca é undefined |
useQuery() em que o componente renderiza o próprio spinner ou erro | useDLE(): { data, loading, error } |
enabled: false | null no lugar dos args: useSuspense(endpoint, id ? { id } : null) retorna undefined e não busca nada |
select | Calcule na renderização, ou use um schema Query lido com useQuery() |
useQueries() | useFetch() para cada um e depois o use() do React: eles fazem fetch em paralelo |
staleTime | dataExpiryLength no endpoint ou na classe base. O padrão é 60 segundos (o do TanStack Query é 0) |
gcTime | o gcPolicy do DataProvider |
retry | Apague: o Data Client não tem loop de retry. Uma requisição com erro é buscada novamente quando um componente precisa dela após errorExpiryLength (padrão de 1 segundo), como o retry: false do TanStack Query |
refetchInterval | pollFrequency no endpoint, lido com useLive() |
refetchOnWindowFocus | Apague: o Data Client não faz novo fetch ao focar a janela |
placeholderData: keepPreviousData | Mude os args dentro de startTransition() (ou use useDebounce() para texto digitado): o React continua mostrando os dados atuais enquanto os próximos carregam |
initialData vindo de uma query de lista | Apague: enquanto os dados da lista estão fresh, uma Entity que ela carregou é renderizada na página de detalhe sem um fetch, quando o schema do endpoint de detalhe é essa Entity |
useMutation() | ctrl.fetch(endpoint, ...args) no event handler, a partir de useController() |
isPending e error de uma mutação | useLoading(): const [run, isPending, error] = useLoading(fn, deps) |
isSuccess, onSuccess, onError | Código após ou ao redor de await ctrl.fetch() (Mutações) |
invalidateQueries() após uma atualização | Apague, quando a resposta é a Entity atualizada |
invalidateQueries() após uma criação | ctrl.fetch(Resource.getList.push, body) (ou unshift); páginas numeradas são diferentes (Mutações) |
invalidateQueries() após uma exclusão | Apague: resource().delete (ou um schema schema.Invalidate) remove a Entity de toda lista |
invalidateQueries() para dados que a resposta não inclui (contagens, totais) | ctrl.expireAll(endpoint): os componentes montados fazem novo fetch |
refetchQueries() | ctrl.fetch(endpoint, args) |
setQueryData() | ctrl.setResponse(endpoint, args, response); para Entities, ctrl.set(Entity, args, value) |
getQueryData() | Em um componente, useCache(). Em outros lugares, ctrl.get(schema, args, ctrl.getState()) |
prefetchQuery() | ctrl.fetchIfStale(endpoint, args), sem await: uma falha nunca rejeita sem tratamento |
ensureQueryData(), getQueryData() ?? fetchQuery() | Dados em cache de ctrl.getResponse() quando podem ser renderizados; senão ctrl.fetchIfStale(endpoint, args) (Loaders) |
fetchQuery() | await ctrl.fetchIfStale(endpoint, args) com um staleTime; ctrl.fetch(endpoint, args) sem ele |
atualização otimista e rollback com onMutate | getOptimisticResponse() no endpoint: o Data Client faz rollback em caso de erro |
useInfiniteQuery() | Uma Collection e ctrl.fetch(endpoint.getPage, args) (Infinite queries) |
onError em QueryCache ou MutationCache (relatório global de erros) | Um Manager de relatório de erros: ele vê todo fetch com falha |
queryClient.clear(), removeQueries() no logout | ctrl.resetEntireStore() |
QueryClientProvider, new QueryClient() | DataProvider |
useQueryClient() | useController() |
ReactQueryDevtools | Apague: o DataProvider adiciona as devtools em desenvolvimento |
HydrationBoundary, dehydrate() | Server Side Rendering |
O useQuery() do próprio Data Client não é o do TanStack Query. Ele lê um schema do store e nunca
faz fetch. Substitua o useQuery() do TanStack Query por useSuspense() ou useDLE().
Provider
Coloque o DataProvider na raiz, fora dos outros providers e dos limites <Suspense> do app, em vez de onde o
QueryClientProvider estava. O limite de reserva dele, que mostra "Uncaught Suspense" em desenvolvimento, captura antes de qualquer
limite acima dele.
import { DataProvider } from '@data-client/react';
import { Suspense, type ReactNode } from 'react';
export const AppProvider = ({ children }: { children: ReactNode }) => (
<DataProvider>
<Suspense fallback={<Loading />}>{children}</Suspense>
</DataProvider>
);
O DataProvider cria seu próprio store, então não há client a criar. Mova os defaultOptions do QueryClient para a classe base
de endpoint, como o mapa de APIs lista.
Leituras
Chame useSuspense() no componente que renderiza os dados e apague o hook useIssues() de cada feature que
envolvia useQuery(). Dois componentes que pedem o mesmo endpoint e os mesmos args compartilham um fetch e uma entrada no store, então
nada se ganha ao compartilhar um hook, e um hook esconde de que o componente depende.
export const issueKeys = {
all: ['issues'] as const,
list: (page: number) => [...issueKeys.all, 'list', page] as const,
detail: (id: number) => [...issueKeys.all, 'detail', id] as const,
};
export const useIssues = (page: number) =>
useQuery({ queryKey: issueKeys.list(page), queryFn: () => fetchIssues(page) });
const { data, isLoading, isError } = useIssues(page);
if (isLoading) return <TableSkeleton />;
if (isError) return <ErrorBanner />;
return <Table rows={data?.results ?? []} />;
import { useSuspense } from '@data-client/react';
import { IssueResource } from './resources/Issue';
export function IssueTable({ page }: { page: number }) {
const { results: issues, pagination } = useSuspense(IssueResource.getList, {
page,
});
return (
<table>
<caption>
Page {pagination.page} of {pagination.pageCount}
</caption>
<tbody>
{issues.map(issue => (
<tr key={issue.id}>
<td>{issue.title}</td>
<td>{issue.state}</td>
</tr>
))}
</tbody>
</table>
);
}
O ramo isLoading vai para um fallback de <Suspense>, e o ramo isError para um error boundary; um
AsyncBoundary é os dois. Mantenha o skeleton e o banner de erro do próprio app como seus fallbacks. A
guarda ?? [] desaparece, porque useSuspense() só retorna quando os dados já estão lá.
Duas chamadas a useSuspense() em um componente carregam uma depois da outra. Quando nenhuma precisa dos dados da outra, inicie as duas
com useFetch() e leia-as com use() (carregamento paralelo de dados).
Respostas com envelope
Quando a API envolve as respostas, como { "results": [...], "pagination": {...} }, descreva o envelope no schema
em vez de desembrulhá-lo, para que os componentes continuem lendo pagination:
import { Entity, resource } from '@data-client/rest';
export class Issue extends Entity {
id = 0;
title = '';
state: 'open' | 'closed' = 'open';
assignee = '';
static key = 'Issue';
}
interface Pagination {
page: number;
pageCount: number;
}
export const IssueResource = resource({
path: '/issues/:id',
searchParams: {} as { page?: number },
schema: Issue,
}).extend(Base => ({
getList: Base.getList.extend({
schema: { results: [Issue], pagination: {} as Pagination },
}),
// a new issue shifts every numbered page, so this POST joins no list: callers expire it
create: Base.getList.push.extend({ schema: Issue }),
}));
searchParams tipa o argumento page da lista. create reutiliza o POST da lista, com o schema simples Issue no
lugar da Collection da lista; Mutações diz quando usá-lo. Quando os itens individuais
também vêm envolvidos, como { "data": {...} }, estenda get da mesma forma: Base.get.extend({ schema: { data: Issue } }).
Mutações
Chame ctrl.fetch() onde o app chamava mutate(). O que onSuccess fazia vai após o await; onError vai em
um catch. Acompanhe o estado pendente e de erro com useLoading().
export const useCloseIssue = () => {
const queryClient = useQueryClient();
return useMutation({
mutationFn: (id: number) => patchIssue(id, { state: 'closed' }),
onSuccess: issue => {
queryClient.invalidateQueries({ queryKey: issueKeys.detail(issue.id) });
toast(`Closed #${issue.id}`);
},
onError: () => toast('Could not close the issue'),
});
};
import { useController, useLoading } from '@data-client/react';
import { IssueResource } from './resources/Issue';
export function CloseIssueButton({ id }: { id: number }) {
const ctrl = useController();
const [close, isPending] = useLoading(async () => {
try {
await ctrl.fetch(IssueResource.partialUpdate, { id }, { state: 'closed' });
toast(`Closed #${id}`);
} catch {
toast('Could not close the issue');
}
}, [ctrl, id]);
return (
<button onClick={close} disabled={isPending}>
Close issue
</button>
);
}
A chamada a invalidateQueries() desapareceu: a resposta é a Issue atualizada, então a tabela e a página de detalhe
mostram a issue fechada. Apps com TanStack Query costumam invalidar a key de detalhe, mas não todas as keys de lista, então as listas mostram dados
desatualizados até expirarem; após a migração, isso não acontece.
Decida o que fazer com cada chamada a invalidateQueries() e refetchQueries() a partir da resposta (mais exemplos em
mutações):
- A resposta é a Entity alterada (update, partial update): apague a chamada, a menos que a alteração mova a Entity
entre listas filtradas ou ordenadas. Fechar uma issue a atualiza em todo lugar, mas não a remove de uma lista
?state=openem cache nem a adiciona a uma?state=closed; mantenha essas corretas comctrl.expireAll(Resource.getList). - Criação: faça fetch do endpoint
push(ouunshift) da lista em vez doPOSTsimples, e a nova Entity entra em todas as listas correspondentes. Isso exige uma Collection no schema da lista:resource()já tem uma por padrão, e um envelope precisa dela por dentro, comoresults: new Collection([Issue]). Para listas divididas em páginas numeradas, em que um novo item desloca todas as páginas, adicione um endpointPOSTsimples (createno exemplo de envelope:Base.getList.push.extend({ schema: Issue })) e depois chamectrl.expireAll(Resource.getList). - Exclusão:
resource().deleteremove a Entity de toda lista. Para um endpoint personalizado, useschema: new schema.Invalidate(MyEntity). Para listas divididas em páginas numeradas, chame tambémctrl.expireAll(Resource.getList): os itens posteriores do servidor sobem uma página, o que as páginas em cache não têm como saber. - Dados que a resposta não inclui (uma contagem, os totais de outro resource):
ctrl.expireAll(endpoint), ou retorne-os na resposta (efeitos colaterais).
Estado de sucesso
useLoading() não tem isSuccess, e a função que ele retorna nunca é rejeitada: ele guarda o erro. Então feche um
formulário ou diálogo após await ctrl.fetch() dentro da função que você passa para useLoading(), não depois de chamar a
função retornada. Para manter uma flag de sucesso:
import { useLoading } from '@data-client/react';
import { useState } from 'react';
export function useMutate<A extends unknown[]>(
mutate: (...args: A) => Promise<unknown>,
deps: readonly unknown[],
) {
const [isDone, setIsDone] = useState(false);
const [run, isPending, error] = useLoading(async (...args: A) => {
setIsDone(false);
await mutate(...args);
setIsDone(true);
}, deps);
return { run, isPending, error, isDone };
}
Loaders e prefetching
Os loaders de roteador que recebem o queryClient passam a receber o Controller. useController() retorna o mesmo
Controller a cada renderização, então é seguro criar o roteador a partir dele.
export const issueLoader =
(queryClient: QueryClient) =>
({ params }: LoaderFunctionArgs) =>
queryClient.ensureQueryData({
queryKey: issueKeys.detail(Number(params.issueId)),
queryFn: () => fetchIssue(Number(params.issueId)),
});
import { ExpiryStatus, type Controller } from '@data-client/react';
import { IssueResource } from './resources/Issue';
export const issueLoader =
(ctrl: Controller) =>
({ params }: { params: { issueId?: string } }) => {
const args = { id: Number(params.issueId) };
const { data, expiryStatus } = ctrl.getResponse(
IssueResource.get,
args,
ctrl.getState(),
);
// fetches only when missing or stale
const fetched = ctrl.fetchIfStale(IssueResource.get, args);
// like ensureQueryData(): cached data, even stale, navigates now; a miss waits for the fetch
return expiryStatus === ExpiryStatus.Valid ? data : fetched;
};
fetchIfStale() faz o fetch apenas quando os dados estão ausentes ou desatualizados, e sempre retorna uma Promise. Sem await, ele funciona
como prefetchQuery(): uma falha nunca rejeita sem tratamento e é armazenada para os componentes exibirem. Use-o também para prefetching
ao passar o mouse ou ao focar: onMouseEnter={() => ctrl.fetchIfStale(IssueResource.get, { id })}. Com await, ele funciona como
fetchQuery() com um staleTime: resolve os dados, esperando o refetch quando os dados em cache estão desatualizados, ou rejeita
com o erro. Use a forma com await onde o loader usava fetchQuery() e o padrão acima onde usava
ensureQueryData() ou getQueryData() ?? fetchQuery(). Route loaders
mostra loaders que não fazem a navegação esperar. Carregue vários endpoints da mesma forma que o loader fazia antes;
deixar a página aparecer antes de os dados secundários chegarem pertence à passada de desempenho.
Infinite queries
useInfiniteQuery() mantém um array de páginas. O Data Client mantém uma única lista: uma Collection à qual cada
nova página é acrescentada. Defina paginationField no endpoint para obter o endpoint getPage dele.
import { Collection, Entity, RestEndpoint } from '@data-client/rest';
export class Note extends Entity {
id = 0;
text = '';
author = '';
static key = 'Note';
}
// every page of one issue's notes shares one list
const issueNotes = new Collection([Note], {
argsKey: ({ issueId }: { issueId: number }) => ({ issueId }),
});
export const getNotes = new RestEndpoint({
path: '/issues/:issueId/notes',
searchParams: {} as { page?: number },
schema: { results: issueNotes, nextPage: 0 as number | null },
paginationField: 'page',
});
export const addNote = new RestEndpoint({
path: '/issues/:issueId/notes',
method: 'POST',
body: {} as { text: string },
schema: issueNotes.push,
});
argsKey deixa page de fora, então toda página e o endpoint push encontram a mesma lista. Uma nova nota aparece sem
invalidar nada.
import { useController, useLoading, useSuspense } from '@data-client/react';
import { getNotes } from './resources/Note';
export function IssueNotes({ issueId }: { issueId: number }) {
const { results: notes, nextPage } = useSuspense(getNotes, { issueId });
const ctrl = useController();
const [loadMore, isLoadingMore] = useLoading(
async (page: number) => ctrl.fetch(getNotes.getPage, { issueId, page }),
[ctrl, issueId],
);
return (
<>
<ul>
{notes.map(note => (
<li key={note.id}>
{note.author}: {note.text}
</li>
))}
</ul>
{nextPage !== null && (
<button onClick={() => loadMore(nextPage)} disabled={isLoadingMore}>
Show older notes
</button>
)}
</>
);
}
pages.flatMap() desaparece. O que getNextPageParam calculava e hasNextPage informava vêm da resposta
(nextPage aqui), que getPage atualiza junto com a lista. isFetchingNextPage é a flag de pendente do useLoading().
Para cursores, veja paginação.
Auth
Bibliotecas como react-query-auth oferecem useUser(), useLogin(), useLogout() e AuthLoader sobre o TanStack
Query. Reconstrua-os a partir de endpoints:
import { useController, useLoading, useSuspense } from '@data-client/react';
import { Entity, RestEndpoint } from '@data-client/rest';
class Account extends Entity {
id = '';
displayName = '';
static key = 'Account';
}
const getSession = new RestEndpoint({
path: '/session',
schema: { account: Account },
});
const signIn = new RestEndpoint({
path: '/session',
method: 'POST',
body: {} as { username: string; password: string },
schema: { account: Account, token: '' },
});
const signOut = new RestEndpoint({ path: '/session', method: 'DELETE' });
export const useAccount = () => useSuspense(getSession).account;
export const useSignIn = (onSuccess?: () => void) => {
const ctrl = useController();
return useLoading(
async (body: { username: string; password: string }) => {
const { account } = await ctrl.fetch(signIn, body);
// the signed-in account becomes the current one without refetching
await ctrl.setResponse(getSession, { account });
onSuccess?.();
},
[ctrl, onSuccess],
);
};
export const useSignOut = (onSuccess?: () => void) => {
const ctrl = useController();
return useLoading(async () => {
await ctrl.fetch(signOut);
await ctrl.resetEntireStore();
onSuccess?.();
}, [ctrl, onSuccess]);
};
Para o cadastro, copie useSignIn() como useSignUp() com o endpoint de cadastro e o tipo do body dele. AuthLoader desaparece: useAccount() suspende
no limite <Suspense> do app até a sessão carregar. Esses hooks envolvem ações, não um vínculo de dados, então vale
a pena mantê-los como hooks.
Os pontos de chamada mudam de forma:
useUser().datapassa a ser o próprio valor:useAccount().useLogin({ onSuccess }).mutate(values)passa a serconst [signIn, isPending] = useSignIn(onSuccess)e depoissignIn(values).
useAccount() precisa que /session responda a um visitante desconectado sem conta, como o userFn do react-query-auth retorna
null. Assim as páginas para visitantes desconectados renderizam, e o novo fetch após resetEntireStore() mostra o estado desconectado. Se a API
responder 401, o erro chega ao error boundary mais próximo, então transforme esse status em uma resposta de desconectado:
import { Entity, NetworkError, RestEndpoint } from '@data-client/rest';
class Account extends Entity {
id = '';
displayName = '';
static key = 'Account';
}
export const getSession = new RestEndpoint({
path: '/session',
schema: { account: Account },
async fetchResponse(input: RequestInfo, init: RequestInit) {
const response = await fetch(input, init);
if (response.status === 401) {
// parseResponse() reads JSON only when the Content-Type says so
return new Response(JSON.stringify({ account: null }), {
headers: { 'Content-Type': 'application/json' },
});
}
if (!response.ok) throw new NetworkError(response);
return response;
},
});
Para fazer logout em qualquer outra resposta 401, adicione o LogoutManager; para o armazenamento de tokens, veja autenticação.
Testes
-
Substitua
QueryClientProvider(e onew QueryClient()de cada teste) nos wrappers de teste porDataProvider, com<Suspense>dentro dele. Cada montagem deDataProvidercomeça com um store vazio. -
Helpers que esperam um spinner desaparecer falham quando os dados já estão no store, porque então nada suspende. Espere apenas quando houver um spinner:
test-utils.tsimport { screen, waitForElementToBeRemoved } from '@testing-library/react';const loadingElements = () => screen.queryAllByTestId(/loading/i);export const waitForLoadingToFinish = async () => {if (loadingElements().length)await waitForElementToBeRemoved(loadingElements);}; -
Servidores mock (MSW,
nock) continuam funcionando sem mudanças. Para renderizar a partir de fixtures sem um servidor, use MockResolver. -
Asserções sobre query keys ou sobre o estado do
queryClientdesaparecem; faça asserções sobre o que é renderizado.
Verifique a migração
- Nenhum arquivo importa
@tanstack/react-query, e não resta nenhumqueryKey,queryOptionsouuseQueryClient. - Todo endpoint que retorna Entities tem um
schema. - O linter passa, incluindo as regras de limite de importação, e nenhuma pasta de feature define uma Entity.
- Cada
<Suspense>ouAsyncBoundaryque captura umuseSuspense()está dentro doDataProvider. - O verificador de tipos, os testes unitários e os testes de ponta a ponta passam.
- Abrir um item de uma lista recém-carregada não faz nenhuma requisição para esse item, quando a lista retorna o item completo.
- Após uma mutação, toda página que mostra aquela Entity mostra a mudança sem recarregar. Um teste que edita um item na sua página de detalhe e depois volta para a lista comprova isso.