Instalación

Instalación de TanStack Query

En esta sección aprenderás a instalar TanStack Query en tu proyecto React y configurarlo correctamente para comenzar a usarlo.

📦 Instalación Básica

Con npm

npm install @tanstack/react-query

Con yarn

yarn add @tanstack/react-query

Con pnpm

pnpm add @tanstack/react-query

🛠️ Configuración Inicial

1. Configurar el Query Client

Crea un Query Client y envuelve tu aplicación con el QueryClientProvider:

import React from 'react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

// Crear una instancia del query client
const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <div className="App">
        {/* Tu aplicación aquí */}
        <h1>Mi App con TanStack Query</h1>
      </div>
    </QueryClientProvider>
  );
}

export default App;

2. Configuración Personalizada del Query Client

Puedes personalizar el comportamiento por defecto:

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

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // Tiempo que los datos se consideran "frescos" (en ms)
      staleTime: 5 * 60 * 1000, // 5 minutos
      // Tiempo que los datos permanecen en cache (en ms)
      cacheTime: 10 * 60 * 1000, // 10 minutos
      // Reintentar peticiones fallidas
      retry: 2,
      // Tiempo de espera para peticiones
      refetchOnWindowFocus: false,
    },
  },
});

🔧 DevTools (Recomendado)

Para una mejor experiencia de desarrollo, instala las DevTools:

npm install @tanstack/react-query-devtools

Y agrégalas a tu aplicación:

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

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <div className="App">
        <h1>Mi App con TanStack Query</h1>
        {/* Tus componentes aquí */}
      </div>

      {/* DevTools - solo en desarrollo */}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

export default App;

📱 Configuración Completa de Ejemplo

Aquí tienes un ejemplo completo de configuración para una aplicación React:

import React from 'react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';

// Importar tus componentes
import Home from './components/Home';
import Users from './components/Users';
import Posts from './components/Posts';

// Configuración del Query Client
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 5 minutos
      cacheTime: 10 * 60 * 1000, // 10 minutos
      retry: (failureCount, error) => {
        // No reintentar errores 404
        if (error.status === 404) return false;
        // Máximo 3 reintentos
        return failureCount < 3;
      },
      refetchOnWindowFocus: false,
    },
    mutations: {
      retry: 1,
    },
  },
});

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Router>
        <div className="App">
          <nav>
            <a href="/">Home</a>
            <a href="/users">Users</a>
            <a href="/posts">Posts</a>
          </nav>

          <main>
            <Routes>
              <Route path="/" element={<Home />} />
              <Route path="/users" element={<Users />} />
              <Route path="/posts" element={<Posts />} />
            </Routes>
          </main>
        </div>
      </Router>

      {/* DevTools */}
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}

export default App;

⚙️ Opciones de Configuración Importantes

Queries por Defecto

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // Tiempo que los datos se consideran frescos
      staleTime: 0, // Por defecto: 0ms (siempre stale)

      // Tiempo en cache antes de ser recolectados por garbage collector
      cacheTime: 5 * 60 * 1000, // Por defecto: 5 minutos

      // Número de reintentos automáticos
      retry: 3, // Por defecto: 3

      // Refetch automático al enfocar la ventana
      refetchOnWindowFocus: true, // Por defecto: true

      // Refetch automático al reconectar la red
      refetchOnReconnect: true, // Por defecto: true

      // Refetch automático al montar el componente
      refetchOnMount: true, // Por defecto: true
    },
  },
});

Mutations por Defecto

const queryClient = new QueryClient({
  defaultOptions: {
    mutations: {
      retry: 0, // Por defecto: no reintentar mutations
    },
  },
});

🚨 Configuración para Producción

Para aplicaciones en producción, considera esta configuración:

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 5 minutos
      cacheTime: 10 * 60 * 1000, // 10 minutos
      retry: (failureCount, error) => {
        // Lógica de retry personalizada
        if (error.status === 404) return false;
        if (error.status >= 500) return failureCount < 3;
        return false;
      },
      retryDelay: attemptIndex => Math.min(1000 * 2 ** attemptIndex, 30000),
      refetchOnWindowFocus: false, // Evitar refetches innecesarios
    },
  },
});

📝 Verificar la Instalación

Crea un componente simple para verificar que todo funcione:

import React from 'react';
import { useQuery } from '@tanstack/react-query';

function TestQuery() {
  const { data, isLoading, error } = useQuery({
    queryKey: ['test'],
    queryFn: () => fetch('https://jsonplaceholder.typicode.com/posts/1').then(res => res.json()),
  });

  if (isLoading) return <div>Cargando...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <h2>✅ TanStack Query funciona!</h2>
      <p>Título del post: {data.title}</p>
    </div>
  );
}

export default TestQuery;

🔍 Verificar DevTools

Si instalaste las DevTools, deberías ver un ícono de TanStack Query en la esquina de tu aplicación. Al hacer clic, se abrirán las herramientas de desarrollo que te permiten:

Ver todas las queries activas
Inspeccionar el estado del cache
Invalidar queries manualmente
Ver el historial de queries
Debuggear mutations

✅ Checklist de Instalación

Instalar @tanstack/react-query
Instalar @tanstack/react-query-devtools (desarrollo)
Crear QueryClient con configuración personalizada
Envolver la app con QueryClientProvider
Agregar ReactQueryDevtools
Crear un componente de prueba
Verificar que las DevTools aparezcan

¡Excelente! Ya tienes TanStack Query instalado y configurado. Ahora vamos a profundizar en la configuración inicial y crear tu primera query.

Próximo paso: Configuración Inicial