El original en inglés cambió después de esta traducción, así que puede estar desactualizada.
Migrar desde TanStack Query
TanStack Query (React Query) guarda en caché la respuesta de cada clave de consulta por separado, así que la aplicación las mantiene consistentes invalidando claves después de cada mutación. Reactive Data Client normaliza las respuestas en Entities: la respuesta de una mutación actualiza todas las listas y los detalles que muestran esa entity, y la mayor parte del código de invalidación desaparece.
La migración sustituye las funciones y las claves de consulta por endpoints con tipos, los hooks por useSuspense()
y llamadas a Controller, y el QueryClient por DataProvider.
Pasos da el orden; Mapa de API da el reemplazo de cada API de TanStack Query.
Migra con tu agente de programación
Pega esto en el chat de tu agente:
La skill de configuración sigue esta guía. Revisa su diff como el de un compañero de equipo.
Pasos
Mantén las pruebas de la aplicación en verde después de cada paso; son la prueba de que el comportamiento no cambió.
- Endpoints y schemas. Convierte cada función de consulta y de mutación en un endpoint: sigue la
configuración de REST para la biblioteca HTTP que llaman las funciones (axios, fetch, ky), y luego dale a cada endpoint un
schemaconstruido con Entities. Sin un schema nada se normaliza, y tendrás que conservar cada llamada ainvalidateQueries. Pon las Entities y los endpoints en una carpeta que cualquier funcionalidad pueda importar (comosrc/resources/), no en la carpetaapi/de cada funcionalidad, aunque los hooks de consulta vivieran allí: una mutación en una funcionalidad suele actualizar la Entity de otra. Si las reglas de lint restringen las importaciones entre carpetas (import/no-restricted-paths,eslint-plugin-boundaries, límites de módulos de Nx), usa una capa compartida que permitan. - Provider. Sustituye
QueryClientProviderporDataProvider(Provider). - Lecturas. Sustituye
useQuery()yuseSuspenseQuery()poruseSuspense()en el componente que renderiza los datos (Lecturas). - Mutaciones. Sustituye
useMutation()porctrl.fetch(), y elimina la invalidación que la normalización hace innecesaria (Mutaciones). - Loaders y precarga. Sustituye
queryClienten los loaders del router y en la precarga al pasar el cursor porctrl.fetchIfStale()(Loaders y precarga). - Consultas infinitas. Sustituye
useInfiniteQuery()por una Collection ygetPage(Consultas infinitas). - Autenticación. Sustituye las bibliotecas de autenticación construidas sobre TanStack Query, como
react-query-auth(Autenticación). - Pruebas. Sustituye
QueryClientProvideren los wrappers de prueba y las suposiciones sobre indicadores de carga (Pruebas). - Limpieza. Elimina las fábricas de claves de consulta, los helpers de
queryOptions()y la configuración al estilolib/react-query.ts. Desinstala@tanstack/react-queryy@tanstack/react-query-devtoolscuando ningún archivo los importe.
Estos pasos conservan el comportamiento de la aplicación, salvo donde Data Client lo corrige con menos código: listas que mostraban datos obsoletos tras una mutación, refetches después de una mutación y fetches de elementos que una lista ya cargó. Los cambios que requieren código adicional o modifican lo que ven los usuarios, como agregar actualizaciones optimistas que la aplicación no tenía, son una pasada de rendimiento aparte y opcional. Termina y verifica primero la migración, para poder medir cada etapa.
Mapa de API
| TanStack Query | Data Client |
|---|---|
queryFn + queryKey, queryOptions() | Un endpoint con un schema. El endpoint y sus args son la clave, así que las fábricas de claves desaparecen |
useQuery(), useSuspenseQuery() | useSuspense(endpoint, args): la carga va al <Suspense> más cercano, los errores al error boundary más cercano, y data nunca es undefined |
useQuery() donde el componente renderiza su propio indicador de carga o error | useDLE(): { data, loading, error } |
enabled: false | null en lugar de los args: useSuspense(endpoint, id ? { id } : null) devuelve undefined y no hace fetch de nada |
select | Calcúlalo al renderizar, o un schema Query leído con useQuery() |
useQueries() | useFetch() para cada uno, y luego use() de React: hacen fetch en paralelo |
staleTime | dataExpiryLength en el endpoint o en la clase base. El valor predeterminado es 60 segundos (el de TanStack Query es 0) |
gcTime | gcPolicy de DataProvider |
retry | Elimínalo: Data Client no tiene un bucle de reintentos. Una petición con error se vuelve a obtener cuando un componente la necesita después de errorExpiryLength (1 segundo por defecto), como el retry: false de TanStack Query |
refetchInterval | pollFrequency en el endpoint, leído con useLive() |
refetchOnWindowFocus | Elimínalo: Data Client no vuelve a obtener los datos al enfocar la ventana |
placeholderData: keepPreviousData | Cambia los args dentro de startTransition() (o useDebounce() para texto escrito): React sigue mostrando los datos actuales mientras se cargan los siguientes |
initialData de una consulta de lista | Elimínalo: mientras los datos de la lista están frescos, una Entity que cargó se renderiza en la página de detalle sin hacer fetch, cuando el schema del endpoint de detalle es esa Entity |
useMutation() | ctrl.fetch(endpoint, ...args) en el manejador de eventos, desde useController() |
isPending, error de una mutación | useLoading(): const [run, isPending, error] = useLoading(fn, deps) |
isSuccess, onSuccess, onError | Código después de await ctrl.fetch() o a su alrededor (Mutaciones) |
invalidateQueries() después de una actualización | Elimínalo, cuando la respuesta es la Entity actualizada |
invalidateQueries() después de una creación | ctrl.fetch(Resource.getList.push, body) (o unshift); las páginas numeradas son distintas (Mutaciones) |
invalidateQueries() después de una eliminación | Elimínalo: resource().delete (o un schema schema.Invalidate) quita la Entity de todas las listas |
invalidateQueries() para datos que la respuesta no incluye (conteos, totales) | ctrl.expireAll(endpoint): los componentes montados vuelven a hacer fetch |
refetchQueries() | ctrl.fetch(endpoint, args) |
setQueryData() | ctrl.setResponse(endpoint, args, response); para Entities, ctrl.set(Entity, args, value) |
getQueryData() | En un componente, useCache(). En otros lugares, ctrl.get(schema, args, ctrl.getState()) |
prefetchQuery() | ctrl.fetchIfStale(endpoint, args), sin await: un fallo nunca provoca un rechazo sin manejar |
ensureQueryData(), getQueryData() ?? fetchQuery() | Los datos en caché de ctrl.getResponse() cuando se pueden renderizar; si no, ctrl.fetchIfStale(endpoint, args) (Loaders) |
fetchQuery() | await ctrl.fetchIfStale(endpoint, args) con un staleTime; ctrl.fetch(endpoint, args) sin él |
Actualización optimista y reversión con onMutate | getOptimisticResponse() en el endpoint: Data Client revierte en caso de error |
useInfiniteQuery() | Una Collection y ctrl.fetch(endpoint.getPage, args) (Consultas infinitas) |
onError en QueryCache o MutationCache (reporte global de errores) | Un Manager de reporte de errores: ve todos los fetches fallidos |
queryClient.clear(), removeQueries() al cerrar sesión | ctrl.resetEntireStore() |
QueryClientProvider, new QueryClient() | DataProvider |
useQueryClient() | useController() |
ReactQueryDevtools | Elimínalo: DataProvider añade las devtools en desarrollo |
HydrationBoundary, dehydrate() | Renderizado del lado del servidor |
Data Client's own useQuery() is not TanStack Query's. It reads a schema from the store and never
fetches. Replace TanStack Query's useQuery() with useSuspense() or useDLE().
Provider
Pon DataProvider en la raíz, fuera de los demás providers de la aplicación y de los límites <Suspense>, en lugar de donde estaba
QueryClientProvider. Su límite de respaldo, que muestra "Uncaught Suspense" en desarrollo, captura antes que cualquier
límite que esté por encima.
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>
);
DataProvider crea su propio store, así que no hay ningún cliente que crear. Mueve los defaultOptions de QueryClient a la clase base
de endpoint, como indica el mapa de API.
Lecturas
Llama a useSuspense() en el componente que renderiza los datos, y elimina el hook useIssues() de cada funcionalidad que
envolvía useQuery(). Dos componentes que piden el mismo endpoint y args comparten un único fetch y una única entrada en el store, así que
compartir un hook no aporta nada, y un hook oculta de qué depende el componente.
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>
);
}
La rama isLoading pasa al fallback de un <Suspense>, y la rama isError a un error boundary; un
AsyncBoundary es ambos. Conserva el esqueleto y el banner de error de la propia aplicación como sus fallbacks. La
protección ?? [] desaparece, porque useSuspense() solo devuelve un valor cuando los datos ya están.
Dos llamadas a useSuspense() en un mismo componente cargan una detrás de otra. Cuando ninguna necesita los datos de la otra, inicia ambas
con useFetch() y léelas con use() (carga de datos en paralelo).
Respuestas con envoltorio
Cuando la API envuelve las respuestas, como { "results": [...], "pagination": {...} }, describe el envoltorio en el schema
en lugar de desenvolverlo, para que los componentes sigan leyendo 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 el argumento page de la lista. create reutiliza el POST de la lista, con el schema simple Issue en
lugar de la Collection de la lista; Mutaciones explica cuándo usarlo. Cuando los elementos individuales
también vienen envueltos, como { "data": {...} }, extiende get del mismo modo: Base.get.extend({ schema: { data: Issue } }).
Mutaciones
Llama a ctrl.fetch() donde la aplicación llamaba a mutate(). Lo que hacía onSuccess va después del await; onError va en
un catch. Sigue el estado pendiente y de error con 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>
);
}
La llamada a invalidateQueries() desaparece: la respuesta es el Issue actualizado, así que la tabla y la página de detalle
lo muestran cerrado. Las aplicaciones con TanStack Query suelen invalidar la clave del detalle pero no todas las claves de lista, así que las listas muestran datos
obsoletos hasta que caducan; tras la migración ya no ocurre.
Decide qué hacer con cada llamada a invalidateQueries() y refetchQueries() según la respuesta (más ejemplos en
mutaciones):
- La respuesta es la Entity modificada (actualización, actualización parcial): elimina la llamada, a menos que el cambio mueva la Entity
entre listas filtradas u ordenadas. Cerrar un issue lo actualiza en todas partes, pero no lo quita de una lista
?state=openen caché ni lo añade a una?state=closed; mantenlas correctas conctrl.expireAll(Resource.getList). - Creación: haz fetch del endpoint
push(ounshift) de la lista en lugar delPOSTsimple, y la nueva Entity se une a todas las listas que correspondan. Esto necesita una Collection en el schema de la lista:resource()la tiene por defecto, y un envoltorio la necesita dentro, comoresults: new Collection([Issue]). Para las listas divididas en páginas numeradas, donde un elemento nuevo desplaza todas las páginas, añade un endpointPOSTsimple (createen el ejemplo del envoltorio:Base.getList.push.extend({ schema: Issue })), y luego llama actrl.expireAll(Resource.getList). - Eliminación:
resource().deletequita la Entity de todas las listas. Para un endpoint personalizado, usaschema: new schema.Invalidate(MyEntity). Para las listas divididas en páginas numeradas, llama también actrl.expireAll(Resource.getList): los elementos posteriores del servidor suben una página, algo que las páginas en caché no pueden saber. - Datos que la respuesta no incluye (un conteo, los totales de otro recurso):
ctrl.expireAll(endpoint), o devuélvelos en la respuesta (efectos secundarios).
Estado de éxito
useLoading() no tiene isSuccess, y la función que devuelve nunca es rechazada: guarda el error en su lugar. Por eso cierra un
formulario o un diálogo después de await ctrl.fetch() dentro de la función que pasas a useLoading(), no después de llamar a la
función devuelta. Para conservar un indicador de éxito:
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 y precarga
Los loaders del router que reciben el queryClient reciben el Controller en su lugar. useController() devuelve el mismo
Controller en cada renderizado, así que es seguro crear el router a partir de él.
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() hace fetch solo cuando los datos faltan o están obsoletos, y siempre devuelve una Promise. Sin await, funciona
como prefetchQuery(): un fallo nunca provoca un rechazo sin manejar, y se almacena para que los componentes lo muestren. Úsalo también para precargar
al pasar el cursor o al enfocar: onMouseEnter={() => ctrl.fetchIfStale(IssueResource.get, { id })}. Con await, funciona como
fetchQuery() con un staleTime: resuelve los datos, esperando el refetch cuando los datos en caché están obsoletos, o se rechaza
con el error. Usa la forma con await donde el loader usaba fetchQuery(), y el patrón anterior donde usaba
ensureQueryData() o getQueryData() ?? fetchQuery(). Loaders de rutas
muestra loaders que no hacen esperar a la navegación. Carga varios endpoints como lo hacía el loader antes;
dejar que la página se muestre antes de que lleguen los datos secundarios corresponde a la pasada de rendimiento.
Consultas infinitas
useInfiniteQuery() mantiene un array de páginas. Data Client mantiene una sola lista: una Collection a la que cada
página nueva se añade. Define paginationField en el endpoint para obtener su endpoint getPage.
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 omite page, así que todas las páginas y el endpoint push encuentran la misma lista. Una nota nueva aparece sin
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. Lo que calculaba getNextPageParam y lo que informaba hasNextPage provienen de la respuesta
(nextPage aquí), que getPage actualiza junto con la lista. isFetchingNextPage es el indicador de estado pendiente de useLoading().
Para los cursores, consulta la paginación.
Autenticación
Bibliotecas como react-query-auth ofrecen useUser(), useLogin(), useLogout() y AuthLoader sobre TanStack
Query. Reconstrúyelos 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 el registro, copia useSignIn() como useSignUp() con el endpoint de registro y el tipo de su body. AuthLoader desaparece: useAccount() se suspende
hasta el límite <Suspense> de la aplicación hasta que se carga la sesión. Estos hooks envuelven acciones, no un enlace de datos, así que
conviene conservarlos como hooks.
Los puntos de uso cambian de forma:
useUser().datapasa a ser el valor en sí:useAccount().useLogin({ onSuccess }).mutate(values)pasa a serconst [signIn, isPending] = useSignIn(onSuccess), y luegosignIn(values).
useAccount() necesita que /session responda a un visitante sin sesión iniciada sin cuenta, como hace el userFn de react-query-auth, que devuelve
null. Así se renderizan las páginas sin sesión, y el nuevo fetch tras resetEntireStore() muestra el estado sin sesión. Si la API
responde 401 en su lugar, el error llega al error boundary más cercano, así que convierte ese estado en una respuesta de sesión no iniciada:
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 cerrar la sesión ante cualquier otra respuesta 401, añade LogoutManager; para el almacenamiento de tokens, consulta la autenticación.
Pruebas
-
Sustituye
QueryClientProvider(y elnew QueryClient()de cada prueba) en los wrappers de prueba porDataProvider, con<Suspense>dentro. Cada montaje deDataProviderempieza con un store vacío. -
Los helpers que esperan a que desaparezca un indicador de carga fallan cuando los datos ya están en el store, porque entonces nada se suspende. Espera solo cuando haya un indicador de carga presente:
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);}; -
Los servidores simulados (MSW,
nock) siguen funcionando sin cambios. Para renderizar a partir de fixtures sin un servidor, usa MockResolver. -
Las aserciones sobre claves de consulta o sobre el estado de
queryClientdesaparecen; haz aserciones sobre lo que se renderiza.
Comprueba la migración
- Ningún archivo importa
@tanstack/react-query, y no queda ningúnqueryKey,queryOptionsniuseQueryClient. - Todo endpoint que devuelve Entities tiene un
schema. - El linter pasa, incluidas sus reglas de límites de importación, y ninguna carpeta de funcionalidad define una Entity.
- Cada
<Suspense>oAsyncBoundaryque captura unuseSuspense()está dentro deDataProvider. - El comprobador de tipos, las pruebas unitarias y las pruebas de extremo a extremo pasan.
- Abrir un elemento desde una lista recién cargada no hace ninguna petición para ese elemento, cuando la lista devuelve el elemento completo.
- Después de una mutación, toda página que muestra esa Entity muestra el cambio sin recargar. Una prueba que edita un elemento en su página de detalle y luego vuelve a la lista lo demuestra.