Feature: Lazy route tree registration for Module Federation micro frontends

[rafaelcardeallodi]

Problem

When using TanStack Router with Module Federation micro frontends (MFEs), the entire route tree must be constructed before createRouter() is called. This means all remote MFE route trees must be fetched and registered upfront at application startup, even if the user will only visit one or two of them during their session.

In our case, we have 13 MFE remotes. We use route.update() and route.addChildren() to inject each remote's route subtree into placeholder routes, then call createRouter(). This forces us to load all 13 remotes at startup via Promise.allSettled, which:

• Increases initial load time — every MFE manifest and entry point must be fetched before the app becomes interactive
• Wastes bandwidth — users typically only access 1-2 MFEs per session
• Creates a single point of failure — a slow or unavailable MFE delays the entire application boot (we mitigate with Promise.allSettled + fallbacks, but it's still suboptimal)

Current workaround

// We wrap everything in a lazy() to defer, but ALL remotes still load together
const AppWithRoutes = lazy(async () => {
  // All 13 MFEs must be registered before createRouter()
  await Promise.allSettled([
    registerSubtree(DashboardRoute, () => loadRemote('dashboard/routeTree')),
    registerSubtree(ProductRoute, () => loadRemote('product/routeTree')),
    // ... 11 more remotes
  ])

  const router = createRouter({ routeTree })
  return { default: () => <RouterProvider router={router} /> }
})

Where registerSubtree does:

async function registerSubtree(baseRoute, subtreeLoader) {
  const { routeTree: subtree } = await subtreeLoader()

  baseRoute.update({
    component: subtree.options.component,
  })

  subtree.children.forEach(route => {
    route.update({ getParentRoute: () => baseRoute })
  })

  baseRoute.addChildren(subtree.children)
}

Proposal

It would be great if TanStack Router supported lazy route tree registration — the ability to dynamically add children to a route at navigation time rather than only at startup.

One possible approach: allow beforeLoad to register child routes dynamically. Something like:

// Ideal API — each MFE loads only when its route is first visited
const dashboardRoute = createRoute({
  getParentRoute: () => appRoute,
  path: 'dashboard',
  beforeLoad: async ({ addChildren }) => {
    const { routeTree } = await loadRemote('dashboard/routeTree')
    addChildren(routeTree.children) // Dynamically register children
  },
})

This way:

• Each MFE's route tree is fetched only when the user navigates to that section
• The router can still be created immediately with just the placeholder routes
• Failed MFE loads only affect the specific route, not the entire app startup

Context

This is a common challenge in Module Federation architectures where the host application doesn't know the remote's route structure ahead of time. The current requirement to have the full route tree before createRouter() makes it difficult to achieve true per-route lazy loading of MFE bundles.

Environment

• @tanstack/react-router (file-based routing with Vite plugin)
• Module Federation via @module-federation/enhanced/runtime
• 13 remote MFEs, each exposing a routeTree

[saravanan10393]

This is much needed one for my project too as i am already having this setup working with react-router and currently migrating it to tanstack router.

[Sm1t]

I also encountered this issue when using TanStack Router with module federation. It would be great if the TanStack team explained the correct way to use TanStack Router with module federation in the documentation.

[arkhipovdenis]

I ran into this same wall, and ended up writing tanstack-router-remote (source) to get around it. We're taking it to production now, so sharing in case it helps anyone here while the thread waits for an official answer.

pnpm add tanstack-router-remote

You create the router with empty placeholder mounts, and each remote's tree gets grafted in later, the first time someone actually opens one of its URLs. Still one router, one history, one route cache. Works with React, Solid and Vue.

const ordersMountRoute = createRemoteRoute({
  getParentRoute: () => rootRoute,
  path: '/orders',
  component: OrdersMount,
})

function OrdersMount() {
  return (
    <RemoteRouteMount
      mountRoute={ordersMountRoute}
      loadRouteTree={async () =>
        (await loadRemote('orders/routeTree')).routeTree
      }
      loading={<Spinner />}
    >
      <Outlet />
    </RemoteRouteMount>
  )
}

So createRouter() fires straight away, and if a remote fails to load it only takes down its own branch instead of your boot.

Direct links were the part that gave me the most trouble. Someone pastes /orders/42 into the address bar and it has to work before that remote tree exists at all. The trick turned out to be leaving the mount static and childless: the fuzzy 404 then lands on the mount itself as a perfectly ordinary match, so its component renders, loads the tree, grafts it, and the very same router rematches the URL. No splat route, no second router, no redirect dance. And it nests: a remote can hold a mount for another remote, and I've got a link four levels deep attaching each tree on the way down.

Fair warning before anyone leans on it: it reaches into internals TanStack hasn't promised to keep (route.update({ getParentRoute }), repeated addChildren(), router.update()). That's why there's a scheduled canary running the suite against the latest published router, and it's already earned its keep. router-core 1.171.16 changed which route owns a not-found boundary, and nested deep links broke completely silently. You'll also need notFoundMode: 'fuzzy', and I haven't gone near streaming SSR or TanStack Start. The rest is written down in limitations.

A thought for the maintainers

Honestly, I don't think this belongs in the router core. Most apps know their whole route tree at build time and would just be carrying the machinery around for nothing. An ecosystem package feels like a better fit, and I'd happily keep maintaining it in that role, under TanStack governance if you'd rather it live there. It's already shaped for it: framework-neutral core with React/Solid/Vue entries, open peer range with the canary watching it, limitations written down as a contract, runnable examples for each transport.

The one thing I can't solve from outside is the route-tree surface I'm reaching through, which is precisely what bit me in 1.171.16. Three small seams would settle it for good:

• an official way to reparent a route and trigger a reindex;
• a supported shape for a remote root sitting below a parent route;
• a stable rule for which route owns the not-found boundary while a descendant mount hasn't attached yet.

The attach signature I landed on, plus the questions I couldn't answer from out here, are in docs/proposal.md. Either way, happy to feed the runtime findings back if any of it is useful.