Clase 03 · Módulo 06
Datos del servidor con TanStack Query
Datos del servidor con TanStack Query
Qué logras en esta clase
Entiendes cómo TanStack Query administra los datos del servidor y revisas con criterio el código que lo usa.
- Lees una consulta: clave, función y estados.
- Decides cuánto tiempo un dato se considera fresco.
- Cambias datos con mutaciones y actualizas las listas afectadas.
- Conectas la librería al teléfono: red y foco.
02
Lo que tendrías que escribir a mano
Con lo visto en el módulo 4, cada pantalla con datos necesita:
- Un estado para los datos, otro para «cargando» y otro para el error.
- Un efecto que pida los datos al entrar.
- Cuidar que una respuesta antigua no pise a una nueva.
Y aun así, al volver se pide todo de nuevo, dos pantallas con el mismo dato hacen dos pedidos y sin señal no hay nada que mostrar.
03
La idea central
TanStack Query guarda una copia con fecha de cada dato del servidor y decide cuándo volver a pedirlo.
04
Qué es TanStack Query
Es una librería que administra el estado del servidor. Al 18-11-2026 su versión mayor vigente es la 5.
npx expo install @tanstack/react-queryNo sabe hablar con tu servidor. Tú le entregas una función que trae los datos (con Supabase, módulo 7) y ella decide cuándo llamarla y guarda el resultado.
05
Las tres piezas
| Pieza | Qué es |
|---|---|
QueryClient | La caché: guarda todas las copias |
QueryClientProvider | Envuelve la app para que todas las pantallas usen esa caché |
useQuery y useMutation | Los hooks con que cada pantalla lee o cambia datos |
El cliente se crea una vez y el proveedor va en el layout raíz (módulo 5). Si Claude crea un cliente nuevo dentro de una pantalla, es un error: cada dibujo partiría con la caché vacía.
06
Leer datos: una consulta
const { data, isPending, isError, refetch } = useQuery({
queryKey: ['productos', categoria],
queryFn: () => traerProductos(categoria),
})Dos cosas obligatorias: la clave (queryKey), que identifica el dato, y la función (queryFn), que devuelve una promesa con el resultado. La consulta devuelve los datos junto con el estado en que se encuentra.
07
La clave es la identidad del dato
La clave es una lista: un nombre y luego todo aquello de lo que el dato depende. ['productos', 'cafés'] y ['productos', 'postres'] son copias distintas.
- Misma clave en dos pantallas: comparten la copia, con un solo pedido.
- Cambia un valor de la clave: se pide el dato nuevo.
08
Los estados que debes dibujar
| Estado | Significa | Qué mostrar |
|---|---|---|
isPending | Todavía no hay datos | Esqueleto o indicador de carga |
isError | El pedido falló | Mensaje y botón para reintentar |
data | Hay datos | El contenido |
isFetching | Hay un pedido en curso | Indicador discreto |
isPending e isFetching no son lo mismo: puedes tener datos en pantalla y una recarga por detrás. Y hay un quinto caso que también se dibuja: la lista llegó, pero vacía.
09
Fresco y viejo
Fresco se muestra sin preguntar. Viejo se muestra igual, pero se vuelve a pedir por detrás.
10
Dos tiempos que gobiernan la caché
| Opción | Qué controla | Por defecto |
|---|---|---|
staleTime | Cuánto tiempo el dato se considera fresco | Viejo de inmediato |
gcTime | Cuánto se conserva una copia que ya nadie usa | 5 minutos |
Con los valores por defecto, cada vez que entras a una pantalla ves la copia al instante y se dispara una recarga. Es seguro, pero puede ser más pedidos de los necesarios.
11
Cuándo se vuelve a pedir un dato viejo
- Al montarse un componente que usa esa consulta.
- Al volver el foco a la app.
- Al recuperarse la conexión.
Si el pedido falla, la librería reintenta tres veces, esperando cada vez más, antes de marcar error.
12
Cómo elegir cuánto dura lo fresco
| Dato | Cambia | Criterio |
|---|---|---|
| Menú de la cafetería | Pocas veces al día | Fresco por varios minutos |
| Estado de un pedido en curso | Cada pocos segundos | Fresco por muy poco |
| Perfil del usuario | Solo cuando él lo edita | Fresco por mucho; se invalida al editar |
No hay un número correcto. Pregunta: ¿qué pasa si el usuario ve esto con un minuto de atraso? Si no pasa nada, dale más tiempo.
13
En el teléfono hay que conectar dos cables
En un navegador, la librería detecta sola la conexión y el foco. En React Native no: hay que conectarlos una vez, al arrancar.
AppState es la pieza de React Native que avisa si la app está en primer plano. Las librerías de red se ven en la clase 5.
14
Error: olvidar esa conexión
Es fácil de comprobar: abre una lista, manda la app a segundo plano, cambia el dato desde otro lado y vuelve. Si la lista no se actualiza sola, falta el cable del foco.
15
Volver a una pantalla que nunca se desmontó
En una pila de navegación (módulo 5), la pantalla anterior sigue montada debajo de la actual. Al volver atrás no se monta de nuevo, así que no recarga.
Dos ajustes que indica la documentación para React Native:
- Recargar lo viejo al recuperar el foco de la pantalla, con
useFocusEffect. - Pausar la suscripción de las pantallas tapadas con la opción
subscribed, para que no se redibujen sin que nadie las vea.
16
Cambiar datos: una mutación
const crear = useMutation({
mutationFn: crearPedido,
onSuccess: () =>
queryClient.invalidateQueries({ queryKey: ['pedidos'] }),
})Una mutación crea, edita o borra en el servidor. Se ejecuta al llamar crear.mutate(datos), por ejemplo al tocar «Confirmar», y tiene sus propios estados, como isPending. queryClient es la caché, que el componente obtiene con el hook useQueryClient.
17
Invalidar: avisar que la copia quedó vieja
No agregas el pedido a la lista a mano. Le dices a la caché que todo lo que parte con ['pedidos'] quedó viejo, y las pantallas que lo usan se actualizan.
18
Las mutaciones no se reintentan solas
A diferencia de las consultas, una mutación que falla no se repite por defecto. Tiene sentido: repetir «crear pedido» puede crear dos.
19
Mostrar el cambio antes de la respuesta
Una actualización optimista dibuja el resultado sin esperar al servidor. La documentación describe dos caminos:
| Camino | Cómo | Cuándo |
|---|---|---|
| Por la interfaz | Dibujas el elemento pendiente con variables de la mutación | El cambio se ve en un solo lugar |
| Por la caché | En onMutate guardas la copia anterior y escribes la nueva; en onError la restauras | Varias pantallas muestran ese dato |
El primero es menos código y no necesita deshacer nada.
20
Optimista no es mentir
Optimista es mostrar el cambio y saber deshacerlo si el servidor dice que no.
21
Tirar hacia abajo para recargar
La consulta entrega refetch, una función que fuerza el pedido. Se conecta al gesto de tirar la lista hacia abajo (módulo 5).
22
Errores que ayudan al usuario
Cuando isError es verdadero:
- Di qué pasó en palabras simples: «No pudimos cargar el menú».
- Ofrece un botón «Reintentar» conectado a
refetch. - Si ya había datos en pantalla, déjalos y avisa que no se pudieron actualizar.
Una pantalla en blanco o un indicador que gira para siempre es peor que un mensaje de error.
23
Lo bueno y lo malo
- A favor: elimina casi todo el código repetido de carga y error, comparte datos entre pantallas y es la base del modo sin conexión.
- En contra: tiene conceptos propios (clave, fresco, invalidar) que hay que entender para revisar el código.
- No conviene: en una app sin servidor, o con un único pedido al abrir.
Alternativa en una línea: SWR hace algo parecido con menos opciones.
24
Qué revisar en el código de Claude
- ¿Hay un solo
QueryClient, creado fuera de las pantallas? - ¿Cada clave incluye todo lo que usa su función?
- ¿Cada pantalla dibuja carga, error y vacío?
- ¿Cada mutación invalida las consultas que afecta?
- ¿Están conectados
onlineManageryfocusManager? - ¿Hay datos del servidor copiados a un
useStateo a Zustand? No debería.
25
Lo que te llevas
- El dato del servidor vive en la caché de TanStack Query, identificado por su clave.
staleTimedecide cuánto dura lo fresco;gcTime, cuánto se guarda lo que nadie usa.- Las mutaciones cambian datos y luego invalidan las consultas afectadas.
- En React Native hay que conectar la red y el foco a mano.
- Carga, error y vacío se dibujan siempre.
26
Hazlo ahora
En 15 minutos, sin base de datos todavía:
- Pídele a Claude Code que instale TanStack Query en el layout raíz, con red y foco.
- Pide una pantalla que lea una lista desde una función que simule al servidor, con dos segundos de espera.
- Comprueba el estado de carga.
- Sal y vuelve a entrar: ¿aparece al instante?
- Haz que la función falle y revisa el mensaje y el botón de reintentar.
Clase terminada
Sigue con la próxima.
Fuentes · revisadas el 18 de noviembre de 2026