Cincuenta componentes montados contra el mismo endpoint disparan cincuenta llamadas idénticas, y cada uno guarda su propio copito de loading. TanStack Query convierte la obtención de datos en caché compartida con reglas explícitas: la clave define la identidad, el tiempo define la frescura, la mutación define la invalidación. Kent C. Dodds, en el artículo Application State Management (kentcdodds.com, 2018), separa el estado de servidor del estado de cliente; la library asume el primero.

La clave como contrato

queryKey: ['todos', userId] declara la identidad del dato. Dos pantallas con la misma clave leen la misma caché. Cambias un parámetro, cambia la clave, y la caché reserva espacio nuevo. staleTime define cuánto tiempo el dato se mantiene fresco sin refetch; gcTime define cuánto tiempo una entrada sin uso se queda en memoria. La documentación de TanStack Query (2025) trata la serialización determinista de la clave como parte del contrato: mismo objeto, mismo orden de propiedades, misma clave.

Dedupe al montar

Tres instancias montadas juntas con la misma clave ejecutan una sola llamada de red: la library deduplica la petición en vuelo. El refetch al foco de la ventana corre por defecto y mantiene fresco el dato de una pestaña que quedó abierta. El modo suspense te entrega el Suspense de React en lugar de un hook de loading; la promesa del query se propaga hasta el boundary más cercano.

Mutación e invalidación

useMutation recibe un onSuccess que llama a invalidateQueries con el prefijo de la lista afectada. Un update optimista escribe en la caché antes de la respuesta y restaura el estado anterior cuando la llamada falla. Dos pantallas que dependen del mismo dato se invalidan juntas; await queryClient.invalidateQueries sostiene el toast hasta que termina el refetch. Una mutación que cambia un ítem de la caché por igualdad usa setQueryData en lugar de un refetch completo.

¿Dónde entra el estado global?

El estado de servidor vive en la caché de queries. El tema, el drawer abierto y los filtros de UI viven en zustand o en contexto. El token de sesión vive en una cookie httpOnly, fuera de la caché serializada. prefetchQuery en el hover del link calienta la caché antes de la navegación; queryClient.getQueryData lee datos cacheados dentro del loader. La frontera entre las dos categorías se vuelve regla de equipo: quien ponga datos remotos en contexto global reimplementa media library, con bug de concurrencia incluido.