Saltar al contenido principal
nota

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:

Copiar el prompt para tu agente de programación

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ó.

  1. 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 schema construido con Entities. Sin un schema nada se normaliza, y tendrás que conservar cada llamada a invalidateQueries. Pon las Entities y los endpoints en una carpeta que cualquier funcionalidad pueda importar (como src/resources/), no en la carpeta api/ 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.
  2. Provider. Sustituye QueryClientProvider por DataProvider (Provider).
  3. Lecturas. Sustituye useQuery() y useSuspenseQuery() por useSuspense() en el componente que renderiza los datos (Lecturas).
  4. Mutaciones. Sustituye useMutation() por ctrl.fetch(), y elimina la invalidación que la normalización hace innecesaria (Mutaciones).
  5. Loaders y precarga. Sustituye queryClient en los loaders del router y en la precarga al pasar el cursor por ctrl.fetchIfStale() (Loaders y precarga).
  6. Consultas infinitas. Sustituye useInfiniteQuery() por una Collection y getPage (Consultas infinitas).
  7. Autenticación. Sustituye las bibliotecas de autenticación construidas sobre TanStack Query, como react-query-auth (Autenticación).
  8. Pruebas. Sustituye QueryClientProvider en los wrappers de prueba y las suposiciones sobre indicadores de carga (Pruebas).
  9. Limpieza. Elimina las fábricas de claves de consulta, los helpers de queryOptions() y la configuración al estilo lib/react-query.ts. Desinstala @tanstack/react-query y @tanstack/react-query-devtools cuando 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 QueryData 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 erroruseDLE(): { data, loading, error }
enabled: falsenull en lugar de los args: useSuspense(endpoint, id ? { id } : null) devuelve undefined y no hace fetch de nada
selectCalcú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
staleTimedataExpiryLength en el endpoint o en la clase base. El valor predeterminado es 60 segundos (el de TanStack Query es 0)
gcTimegcPolicy de DataProvider
retryElimí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
refetchIntervalpollFrequency en el endpoint, leído con useLive()
refetchOnWindowFocusElimínalo: Data Client no vuelve a obtener los datos al enfocar la ventana
placeholderData: keepPreviousDataCambia 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 listaElimí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ónuseLoading(): const [run, isPending, error] = useLoading(fn, deps)
isSuccess, onSuccess, onErrorCódigo después de await ctrl.fetch() o a su alrededor (Mutaciones)
invalidateQueries() después de una actualizaciónElimínalo, cuando la respuesta es la Entity actualizada
invalidateQueries() después de una creaciónctrl.fetch(Resource.getList.push, body) (o unshift); las páginas numeradas son distintas (Mutaciones)
invalidateQueries() después de una eliminaciónElimí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 onMutategetOptimisticResponse() 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ónctrl.resetEntireStore()
QueryClientProvider, new QueryClient()DataProvider
useQueryClient()useController()
ReactQueryDevtoolsElimínalo: DataProvider añade las devtools en desarrollo
HydrationBoundary, dehydrate()Renderizado del lado del servidor
aviso

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.

provider.tsx
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.

Before
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) });
Before, in IssueTable
const { data, isLoading, isError } = useIssues(page);
if (isLoading) return <TableSkeleton />;
if (isError) return <ErrorBanner />;
return <Table rows={data?.results ?? []} />;
After
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:

resources/Issue.ts
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().

Before
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'),
});
};
After
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=open en caché ni lo añade a una ?state=closed; mantenlas correctas con ctrl.expireAll(Resource.getList).
  • Creación: haz fetch del endpoint push (o unshift) de la lista en lugar del POST simple, 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, como results: new Collection([Issue]). Para las listas divididas en páginas numeradas, donde un elemento nuevo desplaza todas las páginas, añade un endpoint POST simple (create en el ejemplo del envoltorio: Base.getList.push.extend({ schema: Issue })), y luego llama a ctrl.expireAll(Resource.getList).
  • Eliminación: resource().delete quita la Entity de todas las listas. Para un endpoint personalizado, usa schema: new schema.Invalidate(MyEntity). Para las listas divididas en páginas numeradas, llama también a ctrl.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:

useMutate.ts
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.

Before
export const issueLoader =
(queryClient: QueryClient) =>
({ params }: LoaderFunctionArgs) =>
queryClient.ensureQueryData({
queryKey: issueKeys.detail(Number(params.issueId)),
queryFn: () => fetchIssue(Number(params.issueId)),
});
After
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.

resources/Note.ts
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.

IssueNotes.tsx
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:

session.ts
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().data pasa a ser el valor en sí: useAccount().
  • useLogin({ onSuccess }).mutate(values) pasa a ser const [signIn, isPending] = useSignIn(onSuccess), y luego signIn(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:

getSession.ts
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 el new QueryClient() de cada prueba) en los wrappers de prueba por DataProvider, con <Suspense> dentro. Cada montaje de DataProvider empieza 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.ts
    import { 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 queryClient desaparecen; haz aserciones sobre lo que se renderiza.

Comprueba la migración​

  • Ningún archivo importa @tanstack/react-query, y no queda ningún queryKey, queryOptions ni useQueryClient.
  • 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> o AsyncBoundary que captura un useSuspense() está dentro de DataProvider.
  • 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.