ADR 009: Evaluación del ecosistema TanStack

Contexto

La plataforma necesita evaluar la compatibilidad del ecosistema TanStack con la arquitectura existente: Module Federation v2, Rsbuild/Rspack y un modelo de micro frontends exclusivamente CSR. Se evaluaron tres productos de TanStack:

1. TanStack Start — un framework full-stack para React (similar a Next.js / Remix)
2. TanStack Router — un router cliente con tipado seguro
3. TanStack Query — una librería de data fetching y caché

Cada uno se evaluó en función de su encaje arquitectónico, compatibilidad con MF v2 y coste de migración.

Decisión — TanStack Start (Rechazado)

TanStack Start (v1.166.1, la última release estable) está construido nativamente sobre Vite desde la v1.121.0. Module Federation v2 tiene soporte de primera clase para Rspack mediante @module-federation/enhanced, pero el soporte para Vite depende del plugin mantenido por la comunidad @module-federation/vite.

Adoptar TanStack Start requeriría reemplazar Rsbuild/Rspack por Vite como herramienta de build, sacrificando:

• Integración nativa con MF v2: El plugin @module-federation/enhanced está diseñado para Rspack. El soporte para Vite mediante @module-federation/vite está mantenido por la comunidad con menos funcionalidades y una API menos estable.
• Carga dinámica de bundles: El protocolo mf-manifest.json de MF v2 permite a la shell resolver y cargar remotos MFE dinámicamente en tiempo de ejecución. Este protocolo no está completamente soportado por el plugin MF para Vite.
• Rendimiento de build: La compilación basada en Rust de Rspack es 5-10x más rápida que los builds de producción basados en Rollup de Vite (ver ADR-008).
• Alineación con la arquitectura CSR: La plataforma es exclusivamente CSR. Las principales propuestas de valor de TanStack Start (SSR, server functions, streaming) son innecesarias y añadirían complejidad sin beneficio.

Decisión — TanStack Router (Propuesto)

Evaluar TanStack Router como reemplazo de react-router ^7.13.1. Esta decisión requiere una evaluación de seguimiento antes de su adopción.

Beneficios potenciales:

• Tipado seguro completo: Los parámetros de ruta, parámetros de búsqueda y datos del loader están completamente tipados. TypeScript detecta referencias a rutas inválidas en tiempo de compilación.
• Agnóstico de bundler: TanStack Router funciona con cualquier bundler, incluido Rsbuild/Rspack. Sin conflicto con MF v2.
• Gestión de search params: Serialización y validación de search params integrada y con tipado seguro mediante integración con zod — un punto de fricción habitual con react-router.
• Devtools: Devtools dedicadas para inspeccionar el estado del router, coincidencias de rutas e historial de navegación.

Cuestiones que requieren evaluación:

• Routing en MFEs: react-router se usa ampliamente en arquitecturas MFE. El patrón singleton de TanStack Router (una única instancia de router por aplicación) necesita validación con el modelo multi-remoto de MF v2, donde cada MFE puede definir sus propias sub-rutas.
• Coste de migración: Todo el código de routing de la shell y los MFEs necesitaría migrarse. Las definiciones de rutas, componentes <Link>, patrones de loader y guards tienen APIs diferentes.
• Madurez de la comunidad: TanStack Router es más reciente y tiene menos recorrido en despliegues de micro frontends en producción comparado con react-router.
• Router singleton compartido: En una arquitectura MFE, la shell posee la instancia del router y los MFEs registran sub-rutas. El patrón para esto en TanStack Router está menos documentado que el enfoque de react-router.

Recomendación: Realizar una prueba de concepto en un único MFE no crítico antes de comprometerse con una migración completa.

Decisión — TanStack Query (Propuesto)

Evaluar TanStack Query para data fetching y caché del lado del cliente en la comunicación con el BFF. Esta decisión requiere una evaluación de seguimiento antes de su adopción.

Beneficios potenciales:

• Caché y deduplicación: Deduplicación automática de peticiones y caché configurable con semántica stale-while-revalidate.
• Refetching en segundo plano: Los datos obsoletos se muestran inmediatamente mientras se obtienen datos frescos en segundo plano, mejorando el rendimiento percibido.
• Actualizaciones optimistas: Soporte integrado para mutaciones optimistas con rollback automático en caso de fallo.
• Devtools: Las TanStack Query Devtools proporcionan visibilidad del estado de la caché, queries activas e historial de mutaciones.
• Instancias por MFE: Cada MFE crea su propia instancia de QueryClient. No se necesita un singleton compartido, evitando el acoplamiento de caché entre MFEs.

Cuestiones que requieren evaluación:

• Dependencia adicional por MFE: Cada MFE que adopte TanStack Query la añade a su bundle. Con la configuración de dependencias compartidas de Module Federation, esto puede mitigarse declarándola como singleton compartido.
• Invalidación de caché entre MFEs: Si el MFE A muta datos que el MFE B muestra, no existe invalidación de caché entre MFEs de forma nativa. Esto debería resolverse mediante el bus de CustomEvents existente o un QueryClient compartido.
• Patrón de integración con BFF: La plataforma usa RPC tipado mediante Cloudflare Service Bindings. Los patrones basados en fetch de TanStack Query necesitan adaptarse al modelo de comunicación con BFF Workers.

Recomendación: Adoptar en un único MFE primero, medir el impacto en el tamaño del bundle y la mejora en DX, y después decidir sobre la adopción a nivel de plataforma.

Consecuencias

Positivas

• El rechazo de TanStack Start evita una migración disruptiva de bundler que socavaría la arquitectura MF v2 de la plataforma.
• La evaluación de TanStack Router puede aportar mejoras significativas en DX mediante routing con tipado seguro, si se puede validar el patrón de integración con MFEs.
• La evaluación de TanStack Query puede reducir el boilerplate para data fetching, caché y estados de carga en los MFEs.

Negativas

• Decisiones diferidas: Router y Query están en estado "Propuesto" en lugar de "Aceptado", lo que significa que los equipos aún no pueden adoptarlos. Esto puede ralentizar a equipos que se beneficiarían de forma inmediata.
• Coste de evaluación: El trabajo de prueba de concepto tanto para Router como para Query requerirá tiempo de ingeniería dedicado.

Alternativas consideradas

Mantener react-router + fetch sin wrapper

Mantener el stack actual (react-router ^7.13.1 + llamadas directas con fetch() a BFF Workers). Coste de migración cero, pero se pierden oportunidades de routing con tipado seguro y caché inteligente. Esta sigue siendo la línea base si las evaluaciones concluyen que TanStack Router/Query no justifican la migración.

SWR (Stale-While-Revalidate de Vercel)

Una alternativa a TanStack Query para data fetching. Más ligera, pero con menos funcionalidades (sin devtools integradas, sin mutaciones optimistas, comunidad más reducida que TanStack Query). Se prefirió TanStack Query para evaluación debido a su conjunto de funcionalidades más completo y su desarrollo activo.

Hooks personalizados

Construir hooks personalizados useFetch / useQuery adaptados al patrón de BFF Workers. Máximo control y cero dependencias externas, pero duplica un esfuerzo significativo que TanStack Query ya resuelve (caché, deduplicación, reintentos, refetch en segundo plano, devtools). Solo viable si TanStack Query resulta inadecuada tras la evaluación.

Documentación Relacionada

• Visión General de Arquitectura — Stack tecnológico y contexto del sistema
• Module Federation — Carga en tiempo de ejecución con MF v2 y dependencias compartidas
• Rsbuild / Rspack — Decisión de bundler (restricción clave para el rechazo de Start)
• Comunicación inter-MFE — Bus de CustomEvents para invalidación de caché entre MFEs