ENES

ADR 009: TanStack Ecosystem Evaluation

Partially Accepted (Start: Rejected, Router: Proposed, Query: Proposed)Date: 2025-03-15

Context

The platform needs to evaluate compatibility of the TanStack ecosystem with the existing architecture: Module Federation v2, Rsbuild/Rspack, and a CSR-only micro frontends model. Three TanStack products were evaluated:

  1. TanStack Start — a full-stack React framework (similar to Next.js / Remix)
  2. TanStack Router — a type-safe client-side router
  3. TanStack Query — a data fetching and caching library

Each was assessed for architectural fit, MF v2 compatibility, and migration cost.

Decision — TanStack Start (Rejected)

TanStack Start (v1.166.1, the latest stable release) is built natively on Vite since v1.121.0. Module Federation v2 has first-class support for Rspack via @module-federation/enhanced, but Vite support relies on the community-maintained @module-federation/vite plugin.

TanStack Start — Rejected TanStack Start — Rejected Reasons Against Vite-based, no native MF v2 Rspack support Loses mf-manifest.json protocol SSR/SSG features unnecessary for CSR-only Dynamic bundle loading incompatible Acknowledged Benefits Full-stack type safety Built-in file-based routing Server functions and SSR Integrated data loading

Adopting TanStack Start would require replacing Rsbuild/Rspack with Vite as the build tool, sacrificing:

  • Native MF v2 integration: The @module-federation/enhanced plugin is designed for Rspack. Vite support via @module-federation/vite is community-maintained with fewer features and a less stable API.
  • Dynamic bundle loading: MF v2's mf-manifest.json protocol enables the shell to dynamically resolve and load MFE remotes at runtime. This protocol is not fully supported by the Vite MF plugin.
  • Build performance: Rspack's Rust-based compilation is 5-10x faster than Vite's Rollup-based production builds (see ADR-008).
  • CSR architecture alignment: The platform is CSR-only. TanStack Start's primary value propositions (SSR, server functions, streaming) are unnecessary and would add complexity without benefit.

Decision — TanStack Router (Proposed)

Evaluate TanStack Router as a replacement for react-router ^7.13.1. This decision requires a follow-up evaluation before adoption.

Potential benefits:

  • Full type safety: Route params, search params, and loader data are fully typed. TypeScript catches invalid route references at compile time.
  • Bundler-agnostic: TanStack Router works with any bundler including Rsbuild/Rspack. No conflict with MF v2.
  • Search param management: Built-in, type-safe search param serialization/validation with zod integration — a common pain point with react-router.
  • Devtools: Dedicated router devtools for inspecting route state, matches, and navigation history.

Concerns requiring evaluation:

  • MFE routing: react-router is widely used in MFE architectures. TanStack Router's singleton pattern (single router instance per app) needs validation with MF v2's multi-remote model, where each MFE may define its own sub-routes.
  • Migration cost: All shell and MFE routing code would need to migrate. Route definitions, <Link> components, loader patterns, and guards all have different APIs.
  • Community maturity: TanStack Router is newer and less battle-tested in production micro frontend deployments compared to react-router.
  • Shared router singleton: In an MFE architecture, the shell owns the router instance and MFEs register sub-routes. The pattern for this in TanStack Router is less documented than react-router's approach.

Recommendation: Conduct a proof-of-concept in a single non-critical MFE before committing to a full migration.

Decision — TanStack Query (Proposed)

Evaluate TanStack Query for client-side data fetching and caching in BFF communication. This decision requires a follow-up evaluation before adoption.

Potential benefits:

  • Caching and deduplication: Automatic request deduplication and configurable cache with stale-while-revalidate semantics.
  • Background refetching: Stale data is shown immediately while fresh data is fetched in the background, improving perceived performance.
  • Optimistic updates: Built-in support for optimistic mutations with automatic rollback on failure.
  • Devtools: TanStack Query Devtools provide visibility into cache state, active queries, and mutation history.
  • Per-MFE instances: Each MFE creates its own QueryClient instance. No shared singleton is needed, avoiding cross-MFE cache coupling.

Concerns requiring evaluation:

  • Additional per-MFE dependency: Every MFE that adopts TanStack Query adds it to its bundle. With Module Federation's shared dependency configuration, this can be mitigated by declaring it as a shared singleton.
  • Cache invalidation across MFEs: If MFE A mutates data that MFE B displays, there is no built-in cross-MFE cache invalidation. This would need to be solved via the existing CustomEvents bus or a shared QueryClient.
  • BFF integration pattern: The platform uses typed RPC via Cloudflare Service Bindings. TanStack Query's fetch-based patterns need to be adapted for the BFF Worker communication model.

Recommendation: Adopt in a single MFE first, measure bundle size impact and DX improvement, then decide on platform-wide adoption.

Consequences

Positive

  • TanStack Start rejection prevents a disruptive bundler migration that would undermine the platform's MF v2 architecture.
  • TanStack Router evaluation may yield significant DX improvements through type-safe routing, if the MFE integration pattern can be validated.
  • TanStack Query evaluation may reduce boilerplate for data fetching, caching, and loading states across MFEs.

Negative

  • Deferred decisions: Router and Query are "Proposed" rather than "Accepted", meaning teams cannot adopt them yet. This may slow down teams that would benefit immediately.
  • Evaluation cost: Proof-of-concept work for both Router and Query will require dedicated engineering time.

Alternatives Considered

Stay with react-router + raw fetch

Keep the current stack (react-router ^7.13.1 + raw fetch() calls to BFF Workers). Zero migration cost, but misses opportunities for type-safe routing and intelligent caching. This remains the baseline if evaluations conclude that TanStack Router/Query do not justify the migration.

SWR (Stale-While-Revalidate by Vercel)

An alternative to TanStack Query for data fetching. Lighter weight, but fewer features (no built-in devtools, no optimistic mutations, smaller community than TanStack Query). TanStack Query was preferred for evaluation due to its richer feature set and active development.

Custom hooks

Build custom useFetch / useQuery hooks tailored to the BFF Worker pattern. Maximum control and zero external dependencies, but duplicates significant effort that TanStack Query already solves (caching, deduplication, retry, background refetch, devtools). Only viable if TanStack Query proves unsuitable after evaluation.

PreviousADR 008: Rsbuild/Rspack as BundlerNextADR 010: Drizzle ORM for D1 Database Access