React Query (TanStack): patrones de obtención de datos

La recuperación de datos en React tiene una superficie sorprendentemente grande: estados de carga, estados de error, recuperación en segundo plano, invalidación de caché después de mutaciones, actualizaciones optimistas, desplazamiento infinito, recuperación previa y deduplicación. Escribir esta lógica a mano con useEffect + useState genera condiciones de carrera, pérdidas de memoria y estados de interfaz de usuario inconsistentes. TanStack Query (anteriormente React Query) v5 resuelve todo esto con una API limpia y componible.

Esta guía cubre los patrones de TanStack Query v5 para aplicaciones React de producción, desde consultas básicas hasta flujos de mutación complejos, actualizaciones optimistas, desplazamiento infinito e integración de Next.js App Router. Cada patrón incluye TypeScript y manejo de errores.

Conclusiones clave

• TanStack Query es una biblioteca de estado del servidor; no la use para el estado de la interfaz de usuario solo del cliente (use Zustand o useState para eso)
• Las claves de consulta son la dirección de caché; incluyen todas las variables que afectan el resultado de la consulta.
• staleTime controla cuándo se activa la recuperación en segundo plano; gcTime controla cuando los datos no utilizados se recolectan como basura
• Las mutaciones deberían invalidar las consultas relacionadas a través de queryClient.invalidateQueries() en onSuccess
• Las actualizaciones optimistas mejoran el rendimiento percibido pero requieren lógica de reversión en onError
• Utilice useInfiniteQuery para listas paginadas; nunca combine useQuery + estado de página del manual
• Captación previa al pasar el mouse para una sensación de navegación instantánea: queryClient.prefetchQuery()
• En Next.js App Router, use HydrationBoundary para deshidratar los datos obtenidos por el servidor en el cliente

---

Instalación y configuración

pnpm add @tanstack/react-query @tanstack/react-query-devtools

// src/providers/query-provider.tsx
'use client';

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { useState } from 'react';

export function QueryProvider({ children }: { children: React.ReactNode }) {
  // Create QueryClient inside component to avoid shared state between requests (SSR safety)
  const [queryClient] = useState(() =>
    new QueryClient({
      defaultOptions: {
        queries: {
          staleTime:            60 * 1000, // 1 minute — data is fresh for 1 minute
          gcTime:           5 * 60 * 1000, // 5 minutes — keep unused cache for 5 minutes
          retry:                        2, // Retry failed requests twice
          retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 30_000), // Exponential backoff
          refetchOnWindowFocus:      true, // Refetch when user returns to tab
          refetchOnReconnect:        true, // Refetch after network reconnect
        },
        mutations: {
          retry: 0, // Do not retry mutations (non-idempotent)
        },
      },
    })
  );

  return (
    <QueryClientProvider client={queryClient}>
      {children}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

// src/app/[locale]/layout.tsx
import { QueryProvider } from '@/providers/query-provider';

export default function LocaleLayout({ children }: { children: React.ReactNode }) {
  return (
    <QueryProvider>
      {children}
    </QueryProvider>
  );
}

---

Claves de consulta: la base

Las claves de consulta son la dirección de caché de sus datos. Cada variable que afecta el resultado de la consulta debe estar en la clave.

// src/lib/query-keys.ts
// Centralize query keys to avoid typos and enable easy invalidation
export const queryKeys = {
  contacts: {
    all:          () => ['contacts'] as const,
    lists:        () => [...queryKeys.contacts.all(), 'list'] as const,
    list:         (filters: ContactFilters) =>
                    [...queryKeys.contacts.lists(), filters] as const,
    details:      () => [...queryKeys.contacts.all(), 'detail'] as const,
    detail:       (id: string) =>
                    [...queryKeys.contacts.details(), id] as const,
  },
  orders: {
    all:    () => ['orders'] as const,
    list:   (orgId: string, page: number) => ['orders', orgId, page] as const,
    detail: (id: string) => ['orders', id] as const,
  },
} as const;

// Usage in queries and invalidations:
// useQuery({ queryKey: queryKeys.contacts.list({ page: 1, limit: 20 }) })
// queryClient.invalidateQueries({ queryKey: queryKeys.contacts.lists() })
// — invalidates ALL list queries regardless of filter parameters

---

Consultas básicas

// src/hooks/use-contacts.ts
import { useQuery } from '@tanstack/react-query';
import { apiFetch } from '@/lib/api';
import { queryKeys } from '@/lib/query-keys';

interface ContactFilters {
  page: number;
  limit: number;
  search?: string;
  status?: string;
}

interface ContactsResponse {
  data: Contact[];
  total: number;
  page: number;
  limit: number;
}

export function useContacts(filters: ContactFilters) {
  return useQuery({
    queryKey: queryKeys.contacts.list(filters),
    queryFn: async () => {
      const params = new URLSearchParams({
        page: String(filters.page),
        limit: String(filters.limit),
        ...(filters.search && { search: filters.search }),
        ...(filters.status && { status: filters.status }),
      });
      return apiFetch<ContactsResponse>(`/contacts?${params}`);
    },
    placeholderData: (previousData) => previousData, // Keep previous page data while fetching
    staleTime: 30_000, // Contacts data: 30 second stale time
  });
}

export function useContact(id: string) {
  return useQuery({
    queryKey: queryKeys.contacts.detail(id),
    queryFn: () => apiFetch<Contact>(`/contacts/${id}`),
    enabled: !!id, // Only fetch if id is provided
  });
}

// Usage in a component
'use client';

export default function ContactsPage() {
  const [page, setPage] = useState(1);
  const [search, setSearch] = useState('');

  const { data, isLoading, isError, error, isFetching } = useContacts({
    page,
    limit: 20,
    search: search || undefined,
  });

  if (isLoading) return <ContactsSkeleton />;
  if (isError) return <ErrorState message={error.message} />;

  return (
    <div>
      {isFetching && <RefetchIndicator />} {/* Shows during background refetch */}
      <ContactsTable data={data.data} />
      <Pagination
        page={page}
        total={data.total}
        limit={20}
        onChange={setPage}
      />
    </div>
  );
}

---

Mutaciones con invalidación de caché

// src/hooks/use-contact-mutations.ts
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { apiFetch } from '@/lib/api';
import { queryKeys } from '@/lib/query-keys';
import { toast } from '@/components/ui/toast';

export function useCreateContact() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (data: CreateContactDto) =>
      apiFetch<Contact>('/contacts', {
        method: 'POST',
        body: JSON.stringify(data),
      }),

    onSuccess: (newContact) => {
      // Invalidate all contact list queries — they are now stale
      queryClient.invalidateQueries({
        queryKey: queryKeys.contacts.lists(),
      });

      // Seed the detail cache immediately — no need to refetch
      queryClient.setQueryData(
        queryKeys.contacts.detail(newContact.id),
        newContact
      );

      toast({ title: 'Contact created', variant: 'success' });
    },

    onError: (error: Error) => {
      toast({ title: 'Failed to create contact', description: error.message, variant: 'destructive' });
    },
  });
}

export function useDeleteContact() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (id: string) =>
      apiFetch(`/contacts/${id}`, { method: 'DELETE' }),

    onSuccess: (_data, deletedId) => {
      // Remove from all list queries
      queryClient.invalidateQueries({ queryKey: queryKeys.contacts.lists() });
      // Remove detail cache
      queryClient.removeQueries({ queryKey: queryKeys.contacts.detail(deletedId) });
      toast({ title: 'Contact deleted', variant: 'success' });
    },
  });
}

---

Actualizaciones optimistas

Las actualizaciones optimistas hacen que las mutaciones parezcan instantáneas al actualizar la interfaz de usuario antes de que el servidor las confirme:

export function useUpdateContact() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: ({ id, data }: { id: string; data: UpdateContactDto }) =>
      apiFetch<Contact>(`/contacts/${id}`, {
        method: 'PATCH',
        body: JSON.stringify(data),
      }),

    // Called immediately before mutationFn
    onMutate: async ({ id, data }) => {
      // Cancel any in-flight refetches for this contact
      await queryClient.cancelQueries({ queryKey: queryKeys.contacts.detail(id) });

      // Snapshot the previous value for rollback
      const previousContact = queryClient.getQueryData<Contact>(
        queryKeys.contacts.detail(id)
      );

      // Optimistically update the UI
      queryClient.setQueryData<Contact>(
        queryKeys.contacts.detail(id),
        (old) => old ? { ...old, ...data } : old
      );

      return { previousContact }; // Passed to onError context
    },

    onError: (_error, { id }, context) => {
      // Roll back to the snapshot on error
      if (context?.previousContact) {
        queryClient.setQueryData(
          queryKeys.contacts.detail(id),
          context.previousContact
        );
      }
      toast({ title: 'Update failed', variant: 'destructive' });
    },

    onSettled: (_data, _error, { id }) => {
      // Always refetch after success or error to sync with server truth
      queryClient.invalidateQueries({ queryKey: queryKeys.contacts.detail(id) });
    },
  });
}

---

Desplazamiento infinito / Paginación

// src/hooks/use-infinite-contacts.ts
import { useInfiniteQuery } from '@tanstack/react-query';

export function useInfiniteContacts(search?: string) {
  return useInfiniteQuery({
    queryKey: ['contacts', 'infinite', search],
    queryFn: ({ pageParam = 1 }) =>
      apiFetch<ContactsResponse>(`/contacts?page=${pageParam}&limit=20${search ? `&search=${search}` : ''}`),

    initialPageParam: 1,
    getNextPageParam: (lastPage) => {
      const nextPage = lastPage.page + 1;
      const maxPage = Math.ceil(lastPage.total / lastPage.limit);
      return nextPage <= maxPage ? nextPage : undefined;
    },

    staleTime: 30_000,
  });
}

// Infinite scroll component
'use client';

import { useInfiniteContacts } from '@/hooks/use-infinite-contacts';
import { useInView } from 'react-intersection-observer';
import { useEffect } from 'react';

export function InfiniteContactsList() {
  const {
    data,
    fetchNextPage,
    hasNextPage,
    isFetchingNextPage,
    isLoading,
  } = useInfiniteContacts();

  const { ref, inView } = useInView({ threshold: 0.5 });

  // Fetch next page when the sentinel element enters the viewport
  useEffect(() => {
    if (inView && hasNextPage && !isFetchingNextPage) {
      fetchNextPage();
    }
  }, [inView, hasNextPage, isFetchingNextPage, fetchNextPage]);

  if (isLoading) return <ContactsSkeleton />;

  const contacts = data?.pages.flatMap((page) => page.data) ?? [];

  return (
    <div>
      {contacts.map((contact) => (
        <ContactCard key={contact.id} contact={contact} />
      ))}

      {/* Sentinel element — triggers next page load when visible */}
      <div ref={ref} className="h-4">
        {isFetchingNextPage && <LoadingSpinner />}
      </div>
    </div>
  );
}

---

Búsqueda previa para navegación instantánea

// Prefetch on hover — data is ready before the user clicks
'use client';

import { useQueryClient } from '@tanstack/react-query';
import { Link } from '@/i18n/navigation';
import { queryKeys } from '@/lib/query-keys';
import { apiFetch } from '@/lib/api';

export function ContactRow({ contact }: { contact: Contact }) {
  const queryClient = useQueryClient();

  const handleMouseEnter = () => {
    queryClient.prefetchQuery({
      queryKey: queryKeys.contacts.detail(contact.id),
      queryFn: () => apiFetch<Contact>(`/contacts/${contact.id}`),
      staleTime: 60_000, // Use cached if less than 1 minute old
    });
  };

  return (
    <tr onMouseEnter={handleMouseEnter}>
      <td>
        <Link href={`/dashboard/contacts/${contact.id}`}>{contact.name}</Link>
      </td>
      <td>{contact.email}</td>
    </tr>
  );
}

---

Consulta Next.js App Router SSR + TanStack

// src/app/[locale]/dashboard/contacts/page.tsx (Server Component)
import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query';
import { queryKeys } from '@/lib/query-keys';
import { getServerContacts } from '@/lib/server-api';
import { ContactsClient } from './contacts-client';

export default async function ContactsPage({ params }: Props) {
  const { locale } = await params;
  const queryClient = new QueryClient();

  // Prefetch on the server — data is embedded in the HTML
  await queryClient.prefetchQuery({
    queryKey: queryKeys.contacts.list({ page: 1, limit: 20 }),
    queryFn: () => getServerContacts({ page: 1, limit: 20 }),
  });

  return (
    // HydrationBoundary serializes the server QueryClient state
    // into the HTML, which the client QueryClient then picks up
    <HydrationBoundary state={dehydrate(queryClient)}>
      <ContactsClient />
    </HydrationBoundary>
  );
}

// src/app/[locale]/dashboard/contacts/contacts-client.tsx ('use client')
'use client';

import { useContacts } from '@/hooks/use-contacts';

export function ContactsClient() {
  const { data } = useContacts({ page: 1, limit: 20 });
  // data is immediately available from the server-dehydrated state
  // No loading state on first render — SSR data is used instantly

  return <ContactsTable data={data?.data ?? []} />;
}

---

Preguntas frecuentes

¿Cuándo debo usar TanStack Query frente a SWR frente a una recuperación simple?

Utilice TanStack Query cuando necesite: invalidación de caché después de mutaciones, actualizaciones optimistas, desplazamiento infinito, recuperación previa, recuperación en segundo plano o solicitud de deduplicación. Utilice SWR si necesita un paquete más pequeño y solo casos de uso simples. Utilice fetch simple en los componentes del servidor Next.js donde desee el almacenamiento en caché de datos nativo de React (la función cache() y el patrón revalidatePath()). TanStack Query es para la interactividad del lado del cliente donde las acciones del usuario afectan los datos del servidor.

¿Cuál es la diferencia entre staleTime y gcTime?

staleTime es el tiempo durante el cual los datos se consideran nuevos; durante este tiempo, no se realiza ninguna recuperación en segundo plano y los datos almacenados en caché se devuelven inmediatamente. Después de que caduque staleTime, los datos quedan "obsoletos" y se recuperarán en segundo plano en el siguiente uso. gcTime (anteriormente cacheTime) es el tiempo que los datos no utilizados (sin suscriptores activos) permanecen en la memoria antes de la recolección de basura. Establezca staleTime según la rapidez con la que cambien sus datos; configure gcTime según el tiempo que desee que la navegación de ida y vuelta se sienta instantánea.

¿Cómo manejo los errores de autenticación (401) globalmente?

Agregue un controlador de errores global en sus opciones predeterminadas de QueryClient. En 401, redirija para iniciar sesión y borre el caché de consultas. En consulta TanStack v5: defaultOptions: { queries: { throwOnError: (error) => { if (error.status === 401) { router.push('/auth/login'); queryClient.clear(); return false; } return true; } } }. Alternativamente, maneje 401 en su ayudante apiFetch llamando a una función logout().

¿Cómo comparto el estado de la consulta entre componentes hermanos sin perforación de puntal?

Cualquier componente que llame a useQuery con la misma clave de consulta comparte los mismos datos almacenados en caché: TanStack Query deduplica las solicitudes automáticamente. Dos componentes ContactsTable y una insignia ContactCount que llama a useContacts({ page: 1, limit: 20 }) con los mismos filtros leerán desde una única solicitud almacenada en caché. Sin perforaciones de utilería, no se necesita contexto.

¿Las claves de consulta deben incluir la sesión del usuario o el ID de la organización?

Sí: si los datos tienen como alcance un usuario u organización, incluya el identificador de alcance en la clave de consulta. Esto evita que los datos de un usuario aparezcan para otro (crítico para aplicaciones multiinquilino). También borre todo el caché de consultas al cerrar sesión: queryClient.clear() o queryClient.removeQueries(); de lo contrario, los datos obsoletos de la sesión anterior pueden parpadear brevemente para el siguiente usuario.

---

Próximos pasos

TanStack Query transforma la recuperación de datos de React de un problema de gestión de estado en un sistema declarativo con reconocimiento de caché. Las actualizaciones optimistas, la captación previa y la hidratación SSR brindan a sus usuarios una experiencia que se siente instantánea, incluso en conexiones lentas.

ECOSIRE crea paneles de administración y portales de clientes de Next.js con TanStack Query para todos los estados del servidor, combinado con Zustand para el estado de la interfaz de usuario solo del cliente y TanStack Table para vistas con muchos datos. Explore nuestros servicios de ingeniería frontend para aprender cómo creamos aplicaciones React de alto rendimiento y listas para producción.