Durante todo el módulo se ha repetido la misma advertencia con distintas palabras: el campo bicicletas está en sliceCatalogo de forma provisional, y src/datos/dominio.js lleva seis módulos fingiendo ser una base de datos. Ha llegado el momento de resolverlo, y la afirmación que lo gobierna todo es esta: los datos que vienen de un servidor no son estado de tu aplicación. No te pertenecen, se quedan obsoletos sin que nadie te avise, otras personas los cambian mientras tú los miras y llegan tarde. Guardarlos en useState o en Redux te convierte en responsable de una lista larguísima de problemas —carga, error, cancelación, condiciones de carrera, peticiones duplicadas, revalidación, invalidación, reintentos, paginación— que ya están resueltos en bibliotecas dedicadas. En esta lección montarás una API ficticia con json-server, aprenderás TanStack Query v5 de verdad —consultas, claves, ciclo de vida de la caché, mutaciones y actualización optimista con reversión—, reescribirás useFetchBicicletas como useBicicletas y compararás el antes y el después, y fijarás la arquitectura final de CicloUrbano: Redux para el estado del cliente, Query para el del servidor. Con esto se cierra el Módulo 7.

1. Por qué los datos remotos no son estado de la aplicación
2. Todo lo que hay que resolver a mano
3. La API ficticia: json-server y db.json
4. TanStack Query v5: instalación y montaje
5. useQuery: la consulta y lo que devuelve
6. Claves de consulta: la identidad de la caché
7. Ciclo de vida de un dato en caché
8. Reintentos, revalidación en foco y paginación
9. Mutaciones con useMutation e invalidación
10. Actualización optimista y su reversión
11. De useFetchBicicletas a useBicicletas
12. Cómo convive con Redux: la arquitectura final
13. Alternativas: RTK Query, SWR y los loader de React Router

La distinción parece filosófica y es completamente práctica. Compara las dos categorías punto por punto.

Un caso concreto de CicloUrbano que lo aclara todo. bici-002 figura como alquilada en tu pantalla. Mientras tú miras el catálogo, la usuaria que la tenía la devuelve en la estación Parque Norte. En ese instante:

• El servidor sabe que bici-002 está disponible.
• Tu almacén de Redux sigue diciendo alquilada.
• Redux está funcionando perfectamente: guarda exactamente lo que le dijiste que guardara.

El problema no es que Redux falle, es que el problema no es de gestión de estado, es de sincronización de una caché. Y una caché tiene preguntas que un almacén de estado no se hace nunca: ¿este dato sigue siendo válido? ¿cuándo lo vuelvo a pedir? ¿qué hago mientras llega el nuevo? ¿cuánto tiempo lo guardo si nadie lo mira?

Redux, el contexto y useState responden «¿cuál es el valor?». Una caché de estado de servidor responde además «¿sigue siendo cierto?».

Esta es la lista completa de lo que tienes que escribir tú si guardas datos remotos en useState o en un slice. Léela entera: es el argumento de la lección.

Los cuatro primeros los resolviste, y costaron una lección entera. Los diez restantes son los que nadie escribe porque son mucho trabajo, y son precisamente los que separan una aplicación que «va» de una que se siente rápida y fiable.

Y hay un coste oculto: cada uno de esos problemas hay que resolverlo por recurso. Bicicletas, estaciones, reservas, usuarios e incidencias, cada uno con su carga, su error, su cancelación y su invalidación. Es cuando se multiplica por cinco cuando la biblioteca deja de ser opcional.

Antes de nada, necesitamos un servidor de verdad. json-server levanta una API REST completa a partir de un fichero JSON, sin escribir una línea de servidor.

Crea db.json en la raíz del proyecto, con los datos canónicos de CicloUrbano:

Arráncalo en el puerto 3001, para no chocar con el 5173 de Vite:

Y añade el atajo en package.json:

A partir de aquí hacen falta dos terminales: npm run dev para la aplicación y npm run api para la API.

Lo que obtienes sin escribir nada de servidor:

json-server escribe de verdad en db.json. Los POST y los PATCH persisten en el fichero, así que puedes recargar la página y ver que la reserva sigue ahí. Es lo que lo hace mucho más útil que un simulacro en memoria: se comporta como un servidor real, incluidos los fallos si le mandas algo mal.

Un consejo práctico: añade db.json a control de versiones pero cuenta con que cambiará al ejecutar la aplicación. Si quieres volver al estado inicial, git checkout db.json.

Y, opcionalmente pero muy recomendable, las herramientas de desarrollo:

TanStack Query gira alrededor de un objeto QueryClient, que es la caché: guarda los datos por clave, sabe cuándo caducan, decide cuándo revalidar y avisa a los componentes suscritos. Es el equivalente conceptual del almacén de Redux, para la otra categoría de estado.

Sobre la colocación: QueryClientProvider va por fuera del Provider de Redux por el mismo motivo que este iba por fuera del enrutador —cualquier componente puede necesitarlo, incluidos los de error de ruta— y porque un thunk de Redux podría querer invalidar consultas, mientras que lo contrario no ocurre. En la práctica los dos órdenes funcionan; lo que no puede es quedar ninguno de los dos por dentro del RouterProvider.

El QueryClient se crea fuera del componente, en su propio módulo. Si lo crearas dentro con new QueryClient() en el cuerpo de un componente, cada render crearía una caché nueva y perderías todo lo guardado.

Los dos parámetros obligatorios:

Regla crítica de queryFn: debe lanzar cuando la petición no va bien. fetch no lanza ante un 404 ni un 500 —solo ante fallos de red—, así que la comprobación de respuesta.ok con su throw es obligatoria. Sin ella, Query considerará un éxito una respuesta de error y guardará en caché el mensaje del servidor como si fuera un dato.

Lo que devuelve useQuery, con las propiedades que se usan a diario:

La distinción entre isPending e isFetching es la que más se falla, y es exactamente la que hace que Query se sienta rápido:

• isPending: no hay nada que enseñar. Toca el indicador de carga a pantalla completa.
• isFetching: hay datos —quizá algo antiguos— y se están refrescando en segundo plano. Enseña los datos y, como mucho, un indicador discreto.

Si usas isFetching donde toca isPending, la pantalla se vaciará cada vez que Query revalide y habrás convertido su mejor característica en un parpadeo.

La queryKey es la identidad del dato en la caché. Dos componentes con la misma clave comparten la misma entrada, la misma petición y los mismos datos; con claves distintas son datos distintos.

Reglas del diseño de claves:

1. De lo general a lo específico, como una ruta. Es lo que permite invalidar por prefijo (apartado 9).
2. Todo lo que cambie el resultado va en la clave. Si queryFn usa estacionId, ese identificador debe estar en la clave; si no, cambiar de estación mostraría los datos de la anterior.
3. Los objetos se comparan por contenido, no por referencia, y el orden de las claves del objeto no importa: { tipo: 'urbana', orden: 'precio' } y { orden: 'precio', tipo: 'urbana' } son la misma clave. Los arrays sí son sensibles al orden.
4. Centraliza las claves en una fábrica, para no escribirlas a mano en veinte sitios:

Con esta fábrica, una errata en una clave deja de ser posible, y renombrar un recurso es cambiar un fichero.

La consecuencia más visible de la clave compartida es la deduplicación automática: si Cabecera, PaginaCatalogo y ResumenFlota piden ['bicicletas'] en el mismo instante, se hace una sola petición y los tres reciben el mismo dato. Ese problema, que en 07-04 requería un condition escrito a mano, aquí no existe.

Aquí está el modelo mental que hay que interiorizar. Un dato en la caché de Query pasa por cuatro situaciones.

Las dos opciones que gobiernan todo esto:

El valor por defecto de staleTime es 0, y sorprende a todo el mundo. Significa que el dato queda obsoleto en cuanto llega, así que Query revalidará en cuanto haya un motivo —montar un componente, volver a la pestaña—. No es un fallo: es un valor conservador, porque Query siempre muestra el dato en caché mientras revalida, así que el usuario no ve una espera, solo una actualización silenciosa. Aun así, en la mayoría de aplicaciones conviene subirlo.

Valores típicos según el tipo de dato:

Una precisión frecuente de confundir: staleTime y gcTime miden cosas distintas. staleTime es «cuánto me fío del dato»; gcTime es «cuánto lo guardo cuando nadie lo mira». Un dato puede estar obsoleto y seguir en memoria durante horas, y por eso al volver a una pantalla ves los datos antiguos al instante mientras Query los refresca por detrás. Esa es exactamente la sensación de aplicación rápida que se buscaba.

Por defecto, Query reintenta tres veces con una espera exponencial antes de dar la consulta por fallida. Se ajusta por consulta:

Reintentar un fallo de red temporal tiene sentido; reintentar un 401 o un 404, ninguno. Filtrar por el tipo de error es lo que distingue un reintento útil de tres peticiones inútiles.

Query revalida los datos obsoletos en cuatro momentos, todos configurables:

La segunda es la que más impresiona la primera vez: dejas la pestaña, vuelves diez minutos después y los datos ya están al día sin que hayas hecho nada. Es uno de los diez problemas de la lista del apartado 2 que nadie escribe a mano.

Para un panel de operario que debe ver la flota casi en directo:

Al cambiar de página, la clave cambia, así que el dato de la página nueva no existe todavía y data sería undefined: la lista desaparecería y volvería. placeholderData lo evita.

Con keepPreviousData, al pulsar «Siguiente» la lista anterior se mantiene visible, isPlaceholderData vale true mientras eso ocurre y el cambio se siente instantáneo. Sin ello, cada cambio de página es un parpadeo a pantalla vacía.

Las consultas leen; las mutaciones escriben. Y una escritura plantea una pregunta que una lectura no tiene: qué datos en caché acaban de quedarse obsoletos.

Lo que devuelve useMutation:

invalidateQueries es la pieza clave, y funciona por prefijo:

Aquí se cobra la regla 1 del apartado 6: claves jerárquicas de lo general a lo específico, porque son las que permiten invalidar una rama entera con una línea.

Qué hace exactamente invalidar: marca las consultas como obsoletas y recarga inmediatamente las que estén activas (con componentes montados). Las inactivas se recargarán cuando alguien las vuelva a montar. No borra nada, así que el usuario sigue viendo los datos anteriores mientras llegan los nuevos.

Invalidar es correcto pero no es instantáneo: el usuario pulsa «Confirmar», espera a que el PATCH termine, espera a que la recarga termine, y entonces ve el cambio. Con una red lenta son dos segundos de nada.

La actualización optimista consiste en aplicar el cambio en la caché antes de que el servidor responda, y deshacerlo si falla. Es el patrón que hace que las aplicaciones buenas se sientan inmediatas.

Los tres pasos son inseparables y cada uno resuelve un problema distinto:

Cuándo usar actualización optimista y cuándo no:

Para confirmar una reserva es defendible; para crear una reserva, no tanto, porque el servidor podría rechazarla si la bicicleta acaba de alquilarla otra persona, y hacer aparecer y desaparecer una reserva es peor que esperar medio segundo. Por eso useCrearReserva invalida y useConfirmarReserva es optimista.

Toca el momento de la verdad. Este era el hook de 05-06, con todo lo que había que hacer a mano:

Y esta es la versión con Query:

El antes y el después, sin adornos:

Fallos concretos que desaparecen sin escribir una línea:

1. Navegar rápido entre dos estaciones y ver la flota de la estación equivocada.
2. Abrir dos paneles que muestran las mismas bicicletas y hacer dos peticiones idénticas.
3. Volver a una pantalla y esperar de nuevo a que carguen datos que ya tenías.
4. Crear una reserva y que el catálogo siga mostrando la bicicleta como disponible.
5. Perder la conexión, recuperarla y quedarte con datos de hace diez minutos.
6. Acumular en memoria los datos de todas las estaciones visitadas en la sesión.

Y una consecuencia de arquitectura importante: sliceCatalogo pierde bicicletas, estadoCarga y error, además del createAsyncThunk cargarBicicletas y sus tres extraReducers. Se queda con termino y orden, que son estado de cliente de verdad. Es exactamente lo que se anunció en 07-04 y en 07-05: hacer y deshacer, tal como pasa en un proyecto real cuando se introduce una biblioteca de estado de servidor.

La regla es de una línea: Redux (o el contexto) para el estado del cliente; TanStack Query para el estado del servidor. No se solapan, no compiten y no hay que elegir.

El reparto final, dato por dato:

Un matiz sobre la sesión que merece pensarse. El usuario es un recurso del servidor —vive en /usuarios—, pero cuál de ellos eres tú en esta pestaña es estado de cliente. Un reparto habitual y muy limpio: la identidad (el token o el identificador) en Redux, y los datos del perfil con useQuery(['usuarios', id]). En CicloUrbano, con un acceso ficticio, mantener el usuario completo en sliceSesion es perfectamente razonable.

Cuánto Redux queda. Después de este movimiento, el almacén de CicloUrbano conserva sliceSesion y un sliceCatalogo reducido a dos campos. sliceReservas desaparece casi entero: las reservas son del servidor, sus transiciones son mutaciones y sus reglas de negocio son del servidor —donde siempre debieron estar—. Esa es la conclusión honesta que se anunciaba en 07-05: en muchas aplicaciones reales, una vez el estado del servidor está en su sitio, el estado de cliente que queda cabe en dos contextos. Es una conclusión legítima, y solo se puede llegar a ella habiendo entendido Redux, no evitándolo.

TanStack Query no es la única respuesta. Estas son las cuatro opciones serias, comparadas.

Cuándo elegir cada una:

• TanStack Query: la opción por defecto hoy. Es la más completa, la mejor documentada, funciona con cualquier forma de obtener datos y no te obliga a adoptar Redux. Es la que se ha usado en esta lección.
• RTK Query: si el proyecto ya usa Redux Toolkit. Defines la API una vez —endpoints, providesTags, invalidatesTags— y te genera los hooks; la invalidación por etiquetas es más declarativa que la de claves. Todo aparece además en Redux DevTools, junto al resto del estado. Su inconveniente es que te ata a Redux.
• SWR: si quieres lo esencial —caché, revalidación en foco, deduplicación— con la menor superficie posible. Menos funciones para mutaciones y paginación, pero muy sólida y minúscula.
• Los loader de React Router (06-03): resuelven un problema distinto y complementario. Un loader carga los datos antes de pintar la ruta, eliminando la cascada «montar → pedir → esperar → pintar» y con ella el parpadeo de carga. Su límite es que la caché va por ruta, no por dato, así que no deduplican entre pantallas ni revalidan en foco. La combinación de los dos es la mejor arquitectura disponible hoy con React Router: el loader precarga la consulta en el queryClient y el componente la lee con useQuery, obteniendo carga anticipada y caché a la vez.

Error 1: que queryFn no lance ante un error HTTP. fetch no lanza con un 404 ni un 500. Sin if (!respuesta.ok) throw, Query guardará el mensaje de error del servidor como si fuera el dato.

Error 2: usar isFetching donde toca isPending. La pantalla se vaciará en cada revalidación y habrás convertido la mejor característica de Query en un parpadeo.

Error 3: dejar fuera de la clave un parámetro que usa queryFn. Si estacionId no está en queryKey, cambiar de estación muestra los datos de la anterior. Todo lo que cambie el resultado va en la clave.

Error 4: crear el QueryClient dentro de un componente. new QueryClient() en el cuerpo de un componente crea una caché nueva en cada render. Va en su propio módulo, fuera.

Error 5: copiar data a un useState o a Redux. Duplica la fuente de verdad y anula la revalidación: tu copia no se entera de nada. Usa data directamente.

Error 6: olvidar cancelQueries en una actualización optimista. Una revalidación en vuelo puede terminar después y pisar tu cambio con los datos viejos. Es un fallo intermitente y muy difícil de diagnosticar.

Error 7: mutar la caché en setQueryData. El actualizador debe devolver un objeto nuevo, igual que un reductor. Mutar el objeto de la caché rompe la comparación de referencias y los componentes no se enteran.

Error 8: invalidar demasiado. invalidateQueries() sin clave invalida todo y provoca una tormenta de peticiones. Invalida solo la rama afectada.

Consejo 1: centraliza las claves en una fábrica. Elimina las erratas, hace explícita la jerarquía y convierte renombrar un recurso en cambiar un fichero.

Consejo 2: ajusta staleTime por tipo de dato. El valor por defecto de 0 es conservador. Las estaciones de CicloUrbano no cambian: una hora está bien y ahorra decenas de peticiones.

Consejo 3: usa las Query DevTools desde el primer día. Enseñan cada consulta con su clave, su estado —fresco, obsoleto, inactivo—, cuándo se pidió por última vez y qué datos tiene. Es el equivalente de Redux DevTools para esta capa.

Consejo 4: encapsula cada consulta en un hook propio. useBicicletas, useEstaciones, useReservas, useCrearReserva. Los componentes no deberían ver queryKey ni queryFn, exactamente por la misma razón por la que no deberían ver la forma del estado de Redux.

Consejo 5: no borres db.json de tu flujo de trabajo. Tener una API que responde de verdad, que persiste y que a veces falla es mucho más formativo que un simulacro que siempre funciona.

Ejercicio 1. Escribe los hooks useEstaciones() y useEstacion(estacionId) sobre la API ficticia, con claves jerárquicas, un staleTime justificado para cada uno y el manejo correcto de errores. Después reescribe PaginaEstaciones para que los use, distinguiendo bien la primera carga de una revalidación.

Ejercicio 2. Este hook de mutación tiene cuatro problemas. Encuéntralos y corrígelo.

Ejercicio 3. Después de este módulo, sliceReservas ha quedado casi vacío. Decide qué se queda en Redux, qué pasa a TanStack Query y qué desaparece por completo, para cada uno de estos elementos, y justifica cada decisión: (a) el array ids y el objeto entidades; (b) estadoCarga y error; (c) estadoEnvio; (d) la regla «solo una reserva activa puede confirmarse»; (e) el createAsyncThunk enviarReserva; (f) el selector seleccionarResumenReservas.

Solución 1.

enabled: Boolean(estacionId) sustituye a la guarda if (!estacionId) return; que en 05-06 había que escribir dentro del efecto. Y fíjate en que este componente resuelve el Ejercicio 2 de 07-01: sin efectos de sincronización, sin derivados guardados y con el estado del servidor donde le corresponde.

Solución 2. Los cuatro problemas:

1. mutationFn no comprueba respuesta.ok ni falta la cabecera Content-Type. Sin la comprobación, un 500 se considera un éxito y la reversión nunca ocurre; sin la cabecera, json-server puede no interpretar el cuerpo.
2. onMutate muta los objetos de la caché. r.estado = 'cancelada' modifica el objeto original dentro de map, así que la «foto» previas también queda alterada: revertir sería imposible aunque hubiera onError.
3. Falta cancelQueries y falta onError. No hay reversión, y una revalidación en vuelo puede pisar el cambio optimista.
4. invalidateQueries() sin clave invalida todas las consultas de la aplicación, provocando una recarga general innecesaria. Y debería ir en onSettled, no en onSuccess, para resincronizar también tras un fallo.

El problema 2 es el más instructivo: una actualización optimista escrita con mutación es peor que no tenerla, porque destruye silenciosamente la única copia que permitía volver atrás. La inmutabilidad no es un capricho de Redux; es lo que hace posible deshacer.

Solución 3.

Y el balance final: de sliceReservas no queda prácticamente nada. Eso no significa que las lecciones 07-03 a 07-05 hayan sido tiempo perdido. El modelo de acciones, reductores puros, estado normalizado y selectores es el que se usa en Zustand, en Jotai, en useReducer y —literalmente— en el setQueryData que acabas de escribir, que es un reductor con otro nombre. Lo que se ha aprendido es a clasificar antes de elegir, y el mejor resultado posible de esa clasificación es descubrir que necesitabas menos de lo que creías.

Los datos que vienen de un servidor no son estado de tu aplicación: no te pertenecen, caducan solos, otros los cambian mientras los miras y llegan tarde. Guardarlos en useState o en Redux no está mal por gusto, está mal porque te hace responsable de una lista de catorce problemas —carga, error, cancelación, condiciones de carrera, deduplicación, revalidación al volver a la pestaña y al reconectar, invalidación tras escribir, reintentos, caché compartida, recolección de memoria, paginación sin parpadeo, datos previos mientras se revalida, actualización optimista— multiplicada por cada recurso. Los cuatro primeros te costaron una lección entera en el módulo 5; los diez restantes son los que nadie escribe a mano.

Has montado una API ficticia real con json-server y un db.json con las cinco bicicletas, las tres estaciones, los dos usuarios y la reserva canónicos de CicloUrbano, servida en http://localhost:3001 con filtros, paginación, ordenación y escrituras que persisten. Sobre ella, TanStack Query v5: un QueryClient creado fuera de los componentes y provisto en main.jsx, useQuery con su queryKey —la identidad de la caché, jerárquica de lo general a lo específico y centralizada en una fábrica— y su queryFn que debe lanzar ante un error HTTP porque fetch no lo hace. Sabes distinguir isPending de isFetching, que es lo que separa una pantalla que parpadea de una que se siente instantánea, y conoces el ciclo de vida de un dato en caché —fresco, obsoleto, inactivo, recolectado— gobernado por staleTime («cuánto me fío») y gcTime («cuánto lo guardo cuando nadie lo mira»), con valores razonados por tipo de dato: una hora para las estaciones, treinta segundos para el catálogo, cero para la disponibilidad en directo. Y las funciones que no se escriben a mano: reintentos filtrados por tipo de error, revalidación al volver a la pestaña y al reconectar, y keepPreviousData para paginar sin vaciar la lista.

En el lado de la escritura, useMutation con invalidateQueries por prefijo —la recompensa directa de las claves jerárquicas— y la actualización optimista completa: onMutate cancelando las revalidaciones en vuelo, guardando la foto anterior y escribiendo el cambio de forma inmutable; onError restaurando esa foto; onSettled resincronizando pase lo que pase. Los tres pasos son inseparables, y una actualización optimista escrita con mutación es peor que no tenerla. useFetchBicicletas se ha convertido en useBicicletas: de cuarenta y cinco líneas a veinte, con seis clases enteras de fallo que dejan de ser posibles y siete funciones nuevas que antes no existían.

La arquitectura final de CicloUrbano queda repartida sin solapamientos: TanStack Query para bicicletas, estaciones, reservas y usuarios; Redux para sliceSesion y un sliceCatalogo reducido a termino y orden; contexto para el tema y los avisos; la URL para el filtro ?tipo=; y useState local para modales, borradores y selecciones. Y la conclusión honesta que este módulo ha ido preparando desde 07-01: cuando el estado del servidor está en su sitio, el estado de cliente que queda es mucho menos del que parecía. A esa conclusión solo se llega habiendo entendido Redux, no evitándolo.

Con esto se cierra el Módulo 7. CicloUrbano ya sabe dónde vive cada dato y por qué, tiene un almacén auditable con historial de acciones, una caché que se sincroniza sola con el servidor y una separación limpia entre lo que es suyo y lo que es del backend. Hace mucho, y lo hace bien. Lo que todavía no hace es ir rápida: hay componentes que se repintan sin necesidad, selectores y cálculos que se rehacen en cada render, listas que vuelven a pintarse enteras porque una prop cambió de identidad, y un paquete final que el navegador descarga entero antes de mostrar la primera pantalla. El Módulo 8: Optimización del Rendimiento ataca precisamente eso: cómo identificar qué renderizado sobra de verdad antes de tocar nada, React.memo para evitar repintados de componentes, useMemo y useCallback —la deuda que este módulo ha ido dejando en 07-02 y 07-05— para estabilizar valores y funciones, la división de código y la carga perezosa para que cada pantalla descargue solo lo suyo, y el React DevTools Profiler para medir en lugar de suponer. La próxima lección es Técnicas de Optimización del Rendimiento en React.