Si trabajas con React y necesitas consumir APIs de forma eficiente, TanStack Query (antes conocido como React Query) te permite manejar peticiones, caché y estados de carga sin escribir código repetitivo. Aquí aprenderás a configurarlo desde cero en un proyecto con Vite y TypeScript para construir una aplicación de cursos paginada.
¿Qué es TanStack Query y por qué cambió de nombre?
La librería dejó de llamarse React Query porque ya no se limita a React. Ahora puedes usarla con Vanilla JavaScript, TypeScript, Vue o Svelte, lo que la convierte en una herramienta versátil para el consumo de APIs.
¿Qué hace TanStack Query? Gestiona peticiones a APIs, almacena resultados en caché mediante una key única y resuelve promesas asíncronas para que tus componentes accedan a los datos sin lógica adicional [01:30].
En React existen varias formas de consumir APIs: la Fetch API nativa, custom hooks, Axios o esta librería. La diferencia con TanStack Query es que añade caché automático y evita el refetch innecesario.
¿Cómo se crea el proyecto base con Vite y TypeScript?
El primer paso es montar el entorno de trabajo y luego instalar la dependencia oficial.
- Ejecuta
npm create vite@latest y nombra el proyecto, por ejemplo my-react-tank-stack-query-app.
- Selecciona React con TypeScript como plantilla.
- Entra a la carpeta y corre
npm install para instalar dependencias base.
- Instala TanStack Query siguiendo el comando que aparece en la documentación oficial.
- Levanta el servidor con
npm run dev para verificar que el proyecto corre [03:10].
Después, organiza la estructura: dentro de public crea una carpeta api con un archivo courses.json, y dentro de src crea las carpetas components y hooks.
¿Qué estructura debe tener el JSON de cursos?
Cada curso es un objeto con cuatro propiedades: id numérico, title, description y duration como strings. Puedes ampliar el JSON con imágenes u otros campos según las necesidades de tu aplicación.
¿Cómo se construye un custom hook con useQuery?
La lógica de la petición vive en un archivo separado llamado useCourses.ts dentro de hooks. Esto mantiene los componentes limpios y centraliza la comunicación con la API.
Primero defines la interfaz en TypeScript para tipar la respuesta:
typescript
interface Course {
id: number;
title: string;
description: string;
duration: string;
}
Luego importas useQuery y QueryFunction desde @tanstack/react-query y creas la función que ejecuta el fetch:
typescript
import { useQuery, QueryFunction } from '@tanstack/react-query';
const fetchCourses: QueryFunction<Course[]> = async () => {
const response = await fetch('/api/courses.json');
if (!response.ok) {
throw new Error('Network response was not ok');
}
return response.json();
};
La función es asíncrona con async/await, captura la respuesta en una variable y valida con un if si la petición fue exitosa. Si falla, lanza un error con un mensaje descriptivo para facilitar la depuración [07:45].
¿Qué papel cumplen la key y la queryFn dentro de useQuery?
El hook personalizado envuelve useQuery y le pasa dos parámetros clave:
typescript
export const useCourses = () => {
return useQuery<Course[], Error>({
queryKey: ['courses'],
queryFn: fetchCourses,
});
};
¿Para qué sirve la queryKey? Funciona como un identificador único que almacena los datos en caché. Así evitas hacer la misma petición varias veces cuando el usuario navega o vuelve a renderizar el componente.
¿Y la queryFn? Es la función que devuelve la promesa con los datos. TanStack Query se encarga de resolverla, manejar los estados de carga y entregarte la información lista para usar.
Los generics <Course[], Error> tipan tanto la respuesta esperada como el posible error, aprovechando la seguridad que ofrece TypeScript.
¿Cómo se conecta el hook con el componente CourseList?
Una vez creado el hook, lo importas en CourseList.tsx y obtienes los datos directamente. TanStack Query te entrega propiedades como data, isLoading y error para renderizar la interfaz según el estado de la petición.
Esta separación entre la lógica de datos y la presentación es una de las ventajas principales de trabajar con custom hooks: el componente solo se preocupa por mostrar la información, mientras el hook maneja la comunicación con la API y el caché.
Con esta base ya puedes implementar paginación, mostrar dos cursos por página o conectar el hook a una API externa real. ¿Has usado TanStack Query en algún proyecto? Cuéntame en los comentarios qué patrón de consumo de APIs prefieres y por qué.
