Fundamentos de TanStack Query: Consultas, caché, mutaciones e invalidación
Aprenda cómo useQuery, queryKey, staleTime, gcTime, useMutation e invalidation trabajan juntos para gestionar el estado del servidor en React sin necesidad de efectos fetch escritos a mano.
Fuentes: Started with React Query
TanStack Query, anteriormente React Query, gestiona los datos que provienen de un servidor. El nombre cambió porque la biblioteca ahora también funciona fuera de React, en Svelte, Vue y Solid. Una forma breve de describirla es como un gestor de estado para el estado del servidor.
Estado del servidor versus estado del cliente
Estado del servidor es el dato que proviene de un backend o de una API externa: usuarios, productos, publicaciones, comentarios. Se encuentra fuera de la aplicación, por lo que esta no lo controla por completo. Puede cambiar sin que la aplicación lo sepa, puede volverse obsoleto y solo se puede acceder a él a través de una solicitud asíncrona.
Estado del cliente pertenece a la propia aplicación. Por ejemplo, si un modal está abierto, esa información solo existe en el navegador, como en const [isModalOpen, setIsModalOpen] = useState(false). Zustand, Redux y Jotai son las herramientas habituales para este tipo de estado.
El enfoque manual y su costo
Si no se cuenta con una biblioteca, la obtención de usuarios suele comenzar con tres elementos de estado.
const [users, setUsers] = useState([])
const [loading, setLoading] = useState(false)
const [error, setError] = useState(null)
Luego un efecto se encarga de la carga.
useEffect(() => {
async function fetchUsers() {
try {
setLoading(true) const res = await fetch(
"https://jsonplaceholder.typicode.com/users"
) const data = await res.json() setUsers(data)
} catch (err) {
setError(err)
} finally {
setLoading(false)
}
} fetchUsers()
Se obtienen los usuarios, se almacenan en el estado, se activa una bandera de carga y se capturan los errores. A medida que la aplicación crece, este patrón se repite en todas partes, y cada versión debe gestionar los estados de carga y error, el caché, la recarga, la recarga en segundo plano, la sincronización y las reintentos. Al aplicar esto a una gran base de código, el resultado es código complicado.
Lo mismo con una consulta
Un único gancho reemplaza el código genérico.
function Users() {
const {
data,
isLoading,
error
} = useQuery({
queryKey: ["users"],
queryFn: fetchUsers
})
Luego, el componente toma un camino diferente según el estado.
if (isLoading) {
return <p>Loading...</p>
} if (error) {
return <p>Something went wrong</p>
} return (
<ul>
{data.map(user => (
<li key={user.id}>
{user.name}
</li>
))}
</ul>
)
}
TanStack Query se encarga de la infraestructura relacionada con los datos del servidor. Su principal ventaja frente a useEffect junto con useState es el caché integrado. Una vez que llegan los datos, estos se almacenan en el caché y pueden reutilizarse posteriormente, lo que reduce las solicitudes innecesarias a la API. Los estados de carga, éxito y error se registran automáticamente, por lo que no es necesario escribir ni mantener lógica manualmente.
Configuración
Instale el paquete.
npm install @tanstack/react-query
Luego cree un QueryClient y póngalo a disposición de la aplicación.
const queryClient = new QueryClient();
root.render(
<QueryClientProvider client={queryClient}>
<App />
</QueryClientProvider>
);
Leer datos con useQuery
El hook useQuery se encarga de las operaciones de lectura, es decir, de todo aquello que obtiene datos del servidor. Una llamada básica se ve así:
const { data,
isPending,
error } = useQuery({
queryKey: ["users"],
queryFn: fetchUsers
})
Requiere un objeto de opciones, y dos propiedades son las más importantes: queryFn y queryKey.
queryFn es la función a la que recurre TanStack Query para obtener los datos. Devuelve los datos directamente o como una Promise, y en caso de error debe lanzar un error o devolver una Promise rechazada.
async function fetchUsers() {
const res = await fetch("/api/users")
if (!res.ok) {
throw new Error("Failed to fetch users")
}
return res.json()
}
Luego se conecta al gancho:
useQuery({
queryKey: ["users"],
queryFn: fetchUsers
})
El queryKey identifica de manera única una consulta y sus datos en caché. Las variables utilizadas por queryFn generalmente deben incluirse en la clave. Por ejemplo, ["users"] podría referirse a todos los usuarios, ["todo", 1] al elemento todo con ID 1 y ["products", "laptops"] a las computadoras portátiles.
El hook devuelve un objeto con el estado de la consulta (cargando, error o éxito), los datos y las funciones para volver a obtenerlos.
Cómo ayuda el caché
Es aquí donde la biblioteca demuestra su utilidad. Los datos obtenidos se almacenan automáticamente y se reutilizan para evitar llamadas redundantes, lo que mejora el rendimiento y acorta el tiempo necesario para mostrar los resultados.
Digamos que el Componente A solicita ["users"]. TanStack Query obtiene y almacena en caché el resultado. Más tarde, el Componente B solicita la misma clave y la biblioteca detecta que los datos ya están en caché. En lugar de que cada componente mantenga su propia copia, TanStack Query gestiona una sola copia en caché del estado del servidor. Esa es una de las mayores diferencias entre el simple fetch() y esta biblioteca.
staleTime y gcTime
staleTime responde a una pregunta: ¿cuánto tiempo deben considerarse frescos estos datos?
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
staleTime: 60,000 // 60 seconds
})
Con esa configuración, los datos están actualizados durante los primeros 60 segundos. Después de un minuto se vuelven obsoletos, lo que permite activar una nueva carga y realizar una actualización en segundo plano. Que estén obsoletos no significa que hayan sido eliminados, aunque los datos puedan estar desactualizados. Una vez obsoletos, se pueden volver a cargar cuando algo lo provoca, como cuando la ventana recupera el foco o se monta un componente.
Ignorar el estado de obsolescencia genera solicitudes innecesarias cuando los usuarios vuelven a visitar una página.
User visits page
↓
Fetch users
↓
User navigates away
↓
User comes back
↓
Fetch users again
Si nada cambia, la segunda solicitud es en vano. Un período de vigencia más largo evita esto:
staleTime: 5 * 60 * 1000
Eso marca los datos como actualizados durante cinco minutos. Recuerde que staleTime controla la actualidad de los datos y no es un intervalo de recarga.
También existe gcTime, el tiempo de recolección de basura. Determina cuánto tiempo permanecen en memoria los datos en caché inactivos y no monitoreados antes de ser recogidos.
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
gcTime: 60000
})
En resumen, staleTime indica cuánto tiempo permanecen actualizados los datos, mientras que gcTime muestra cuánto tiempo se mantienen las entradas de caché no utilizadas. Cada uno resuelve problemas diferentes.
Recargar datos
Las consultas obsoletas pueden recargarse cuando se monta un componente, la ventana vuelve a tener foco o la red se reconecta, y estos comportamientos son configurables. También existe la posibilidad de realizar un recargo manual.
const { refetch } = useQuery(...)
refetch()
También es posible realizar encuestas.
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
refetchInterval: 30,000
})
La consulta vuelve a obtener datos aproximadamente cada 30 segundos mientras está activa. Esta operación reemplaza los datos obsoletos por datos actualizados provenientes del servidor.
Cambiar datos con useMutation
Hasta ahora todo se ha referido a la lectura de datos. La creación, actualización o eliminación (POST, PUT, PATCH, DELETE) se realiza a través del hook useMutation. Como ejemplo, aquí está la forma de crear un usuario. Primero viene la función de mutación.
async function createUser(user) {
const response = await fetch(
"https://jsonplaceholder.typicode.com/users",
{
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify(user),
}
);
if (!response.ok) {
throw new Error("Failed to create user");
}
return response.json();
}
A continuación, se pasa a useMutation.
import { useMutation } from "@tanstack/react-query";
function CreateUser() {
const mutation = useMutation({
mutationFn: createUser,
});
return (
<button
onClick={() =>
mutation.mutate({
name: "John Doe",
email: "john@example.com",
})
}
disabled={mutation.isPending}
>
{mutation.isPending ? "Creating..." : "Create User"}
</button>
);
}
export default CreateUser;
Al hacer clic en el botón, se activa la mutación mediante mutation.mutate().
Button click
↓
mutation.mutate(user)
↓
createUser(user)
↓
POST request
↓
Server
Tenga en cuenta que createUser() nunca se llama directamente. El componente llama a mutation.mutate() y TanStack Query invoca esa función.
Las mutaciones también tienen banderas de estado, al igual que las consultas.
const {
mutate,
isPending,
isSuccess,
isError,
error,
data,
} = useMutation({
mutationFn: createUser,
});
Ellos controlan la interfaz de usuario.
<button
onClick={() => mutate({ userName: "delfina ghimire" })}
disabled={isPending}
>
{isPending ? "Creating..." : "Create user"}
</button>
Una vez que se ejecuta mutate(), la mutación pasa por varios estados:
isPending: la mutación está en ejecución.isSuccess: finalizó con éxito.isError: falló.data: el resultado de una mutación exitosa.error: detalles en caso de fallo.mutate: el desencadenante, que acepta las variables para la función de mutación.
Eso hace que sea sencillo proporcionar retroalimentación durante una operación de creación, actualización o eliminación.
QueryClient y la invalidación
QueryClient es un objeto central que gestiona la caché y coordina el comportamiento de las consultas y mutaciones. Se crea inicialmente con new QueryClient(), y dentro de un componente se accede a él mediante useQueryClient(). Permite invalidar consultas, actualizar datos en caché, eliminar datos en caché, restablecer consultas y realizar precarga. Una llamada típica es queryClient.invalidateQueries({ queryKey: ["users"] }).
La invalidación es especialmente importante después de las mutaciones. Cuando una mutación modifica los datos del servidor, las consultas relacionadas pueden contener resultados obsoletos, y al invalidarlas se marcan como anticuadas para que puedan volverse a obtener. Supongamos que la caché contiene a dos usuarios:
[
{ id: 1, userName: "delfina ghimire" },
{ id: 2, userName: "spiderman ghimire" },
]
Se crea entonces un nuevo usuario.
mutation.mutate({
userName: "ironman ghimire",
});
El servidor ahora tiene tres usuarios, pero la caché sigue mostrando dos. La consulta ["users"] puede marcarse como obsoleta. Primero se obtiene el cliente:
const queryClient = useQueryClient();
Luego, la mutación se invalida al tener éxito.
const mutation = useMutation({
mutationFn: createUser,
onSuccess: () => {
queryClient.invalidateQueries({
queryKey: ["users"],
});
},
});
El flujo se desarrolla de la siguiente manera:
Create Users (Mutation)
↓
Server data changes
↓
Invalidate ["users"]
↓
Query becomes stale
↓
Refetch
↓
UI gets fresh data
Para aclarar los términos: invalidate marca los datos en caché como obsoletos, mientras que refetch los carga nuevamente de inmediato. Invalidar una consulta activa generalmente provoca un recarga automática.
La imagen general
Todos estos elementos forman una historia coherente:
- TanStack Query gestiona los datos del servidor.
- La lectura se realiza mediante
useQuery. - Los datos obtenidos se almacenan en la caché de consultas.
staleTimedetermina cuándo los datos en caché se consideran actualizados.gcTimedecide cuánto tiempo permanecen las entradas de caché sin usar.- La recarga decide cuándo se vuelven a cargar los datos.
- La creación, actualización y eliminación se realizan a través de
useMutation. - QueryClient coordina las consultas, mutaciones y la caché.
- La invalidación de consultas indica que los datos en caché están desactualizados.
Con estas relaciones claras, resulta mucho más fácil comprender la biblioteca.
Leer más
- De prototipo a producción: IA agente con LangChain, LangGraph y Azure — Búsqueda híbrida, cachés de embeddings, enrutamiento con LangGraph, interruptores de circuito, pruebas de regresión con conjunto de datos de referencia y seguimiento para un agente de documentos fiscales, con resultados presentados.
- Deja de entregar a tus agentes de IA sus sueños: un proceso centrado en especificaciones para equipos pequeños — Cómo un equipo pequeño lanza productos con agentes de IA: especificaciones escritas, revisión por parte de dos familias de modelos, pruebas en tiempo de ejecución, fusión de resultados por humanos y un orquestador que recuerda todo.