RFC: Support custom router implementations

[obedm503]

Today, the file-based routing generator always imports from the official router module for the selected target (e.g., @tanstack/react-router). I'm proposing a routerModule config option that lets the generator import from a custom module instead. This would let third-party router implementations for runtimes like NativeScript, React Native, OpenTUI, or others reuse TanStack Router's routing conventions without needing to become official targets.

I'm building a TanStack Router binding for SolidJS and NativeScript on top of @tanstack/router-core. It had to be a new package because web navigation doesn't always map cleanly to native apps and because I'm rendering native views. For example, per-tab routing: each tab owns its own navigation stack, switching tabs preserves each stack's history, and back applies to the active stack. This needs a router built around native views and native navigation instead of the DOM and browser APIs.

Even though the implementation looks different under the hood, the rest of TanStack Router is a great fit. Features like loaders, search param validation, and the file-based routing infrastructure (route tree generation, generated types, import management, etc.) all carry over. I want to reuse all of this without TanStack Router needing to support NativeScript or maintain this integration.

Current limitation

Today, the generator derives the router module directly from target:

Target	Router module
react	@tanstack/react-router
solid	@tanstack/solid-router
vue	@tanstack/vue-router

This means target answers two questions at once: which build pipeline to use, and which module provides the router APIs. This works for the official integrations, but a native renderer can still use the Solid, React, or Vue pipeline while importing its router APIs from a different module.

If a route imports createFileRoute from a compatible custom module, the generator doesn't recognize it and injects a second, conflicting import during normalization. I can work around this with bundler and TypeScript aliases, but that requires every tool in the chain to agree on the mapping, and generated routes still reference the wrong package.

Proposal

Add an optional routerModule option:

tanstackRouter({
  target: "solid",
  routerModule: "@acme/native-router",
});

When omitted, nothing changes:

const routerModule = `@tanstack/${config.target}-router`;
// becomes
const routerModule = config.routerModule ?? `@tanstack/${config.target}-router`;

target says how code should be generated, routerModule says where the router APIs come from. The specifier replaces the default module in generated route files, import normalization, and any generated re-exports or type augmentations. Nothing else about the generator changes.

The custom module needs to export the same API surface the selected target pipeline expects (e.g., createFileRoute, createLazyFileRoute, createRootRoute, etc.). TanStack Router wouldn't validate this at build time. TypeScript can handle it. Integration authors own testing and supporting their own environments.

What this could unlock

This small change could let TanStack Router's file-based routing conventions and type system travel beyond the browser without asking the core project to own every router implementation. The community gets to explore new routing models, prove them in real apps, and share them independently, with TanStack Router as the common foundation.

I have a working implementation ready for review and I'm happy to adjust the API or scope based on feedback.