Make react router as peer dep instead of dependency

[adgang]

I came across this while debugging #3002

Some package managers/resolvers in certain cases, load different downstream packages for different imports.
For instance, in tanstack/start quick starter app, we import both @tanstack/start and @tanstack/router. @tanstack/router is imported in user application(See Getting Started) as well in @tanstack/start. In one place the resolver may resolve to a different module than in the other places.

deno, for instance resolves

1. the import of @tanstack/react-router in user application to node_modules/.deno/@TanStack+react-router@1.87.12_1 and
2. the import of @tanstack/react-router in @tanstack/start to node_modules/.deno/@TanStack+react-router@1.87.12

This causes a null router value to be returned by useRouterState() and the following logs:

Warning: useRouter must be used inside a <RouterProvider> component!

when the <Outlet /> code ultimately fetches context.

In other words, the module that hung the context up was in ssr.tsx via createStartHandler/StartServer was node_modules/.deno/@tanstack+react-router@1.87.12_1(because resolver resolved to that module)
While, the code uses(and gets from resolver) node_modules/.deno/@tanstack+react-router@1.87.12

pnpm/deno/bun/yarn all three can resolve to different modules this way.

Related issues:
#3002 - deno issue
#2594 - refers to bun and pnpm
#2540 - refers to pnpm and yarn
#1692 - doesn't mention the package manager used, but seems to indicate a similar issue.

I have fixed only the react-router issue for now. But if people used @tanstack/react-cross-context directly in their code, then they will see this issue there as well.

This means that potentially all the libraries in tanstack start/router should be appropriately set as peer dependencies instead of dependencies as a matter of best practice(because unlike a typical monorepo tanstack router packages should be independently usable as well). I will leave it for @tannerlinsley if/when he wants to do these changes, if he accepts this fix.

At the very least, @tanstack/react-cross-context should be declared as peer dependency in @tanstack/router as it is the container where we hang up the context(a singleton). Otherwise people will use it in their code and end up with two different contexts and will end up hitting their heads against the wall on why their context is empty in some part of the code while it is correctly obtained in other places(or worse they will have some 10 contexts).

The potential packages can be seen by dependency tree where this practice should apply:

deno info @tanstack/start | grep tanstack
├─┬ npm:/@tanstack/react-cross-context@1.87.6_react@19.0.0_react-dom@19.0.0__react@19.0.0 (7.43KB)
├─┬ npm:/@tanstack/react-router@1.87.12_react@19.0.0_react-dom@19.0.0__react@19.0.0_@tanstack+router-generator@1.87.7 (1.63MB)
│ ├── npm:/@tanstack/history@1.87.6 (71.85KB)
│ ├─┬ npm:/@tanstack/react-store@0.6.1_react@19.0.0_react-dom@19.0.0__react@19.0.0 (13.48KB)
│ │ ├── npm:/@tanstack/store@0.6.0 (15.2KB)
│ ├─┬ npm:/@tanstack/router-generator@1.87.7 (353.33KB)
│ │ ├── npm:/@tanstack/virtual-file-routes@1.87.6 (23.26KB)
├── npm:/@tanstack/router-generator@1.87.7 (353.33KB) *
├─┬ npm:/@tanstack/router-plugin@1.87.13_vite@6.0.3_@babel+core@7.26.0_@types+node@22.5.4 (280.35KB)
│ ├── npm:/@tanstack/router-generator@1.87.7 (353.33KB) *
│ ├── npm:/@tanstack/virtual-file-routes@1.87.6 (23.26KB)
├─┬ npm:/@tanstack/start-vite-plugin@1.87.14_@babel+core@7.26.0 (134.55KB)

BTW this issue can show up in node as well if npm installs nested dependencies. I am not 100% sure on the module resolution logic of current npm but I believe at least older npm versions used to do this.

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit e98f51c. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

---

✅ Successfully ran 2 targets

• nx affected --targets=test:eslint,test:unit,test:e2e,test:types,test:build,build --parallel=3
• nx run-many --target=build --exclude=examples/** --exclude=e2e/**

---

Sent with 💌 from NxCloud.

[schiller-manuel]

start cannot be used without router, so a peer dependency is not expressing the correct relationship.

[pkg-pr-new]

Open in Stackblitz

More templates

• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-file-based-codesplitting
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-rsc
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-example-large
• tanstack-start-example-supabase-basic
• tanstack-start-example-trellaux
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query

@tanstack/arktype-adapter

npm i https://pkg.pr.new/@tanstack/arktype-adapter@3001

@tanstack/history

npm i https://pkg.pr.new/@tanstack/history@3001

@tanstack/create-router

npm i https://pkg.pr.new/@tanstack/create-router@3001

@tanstack/react-cross-context

npm i https://pkg.pr.new/@tanstack/react-cross-context@3001

@tanstack/react-router

npm i https://pkg.pr.new/@tanstack/react-router@3001

@tanstack/react-router-with-query

npm i https://pkg.pr.new/@tanstack/react-router-with-query@3001

@tanstack/router-cli

npm i https://pkg.pr.new/@tanstack/router-cli@3001

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/@tanstack/eslint-plugin-router@3001

@tanstack/router-devtools

npm i https://pkg.pr.new/@tanstack/router-devtools@3001

@tanstack/router-generator

npm i https://pkg.pr.new/@tanstack/router-generator@3001

@tanstack/router-plugin

npm i https://pkg.pr.new/@tanstack/router-plugin@3001

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/@tanstack/router-vite-plugin@3001

@tanstack/start

npm i https://pkg.pr.new/@tanstack/start@3001

@tanstack/start-vite-plugin

npm i https://pkg.pr.new/@tanstack/start-vite-plugin@3001

@tanstack/valibot-adapter

npm i https://pkg.pr.new/@tanstack/valibot-adapter@3001

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/@tanstack/virtual-file-routes@3001

@tanstack/zod-adapter

npm i https://pkg.pr.new/@tanstack/zod-adapter@3001

commit: e98f51c

[adgang]

May be we can expose all functions like createRouter from start then? By reexporting I mean.

[schiller-manuel]

this seems like a workaround for some bundler issues. what's the proper solution here?

[SeanCassiere]

Since we have it documented pretty much everywhere, that start is meant to be used with router, I think its fine to move it to peerDeps.

[SeanCassiere]

It may be worth checking out, whether we are actually using the react-cross-context package and possibly remove it.

[arfath-linklet]

We faced this issue after nuking node_modules, removing package-lock and re-installing. I'm unsure on how tanstack packages follow semantic versioning. Should peer-dep only point to patch versions or minor versions also? To get around this issue we are currently overriding internal deps to stay within patch range. Example in pnpm:

"pnpm": {
    "overrides": {
      "@tanstack/react-router": "~1.98.0",
      "@tanstack/router-generator": "~1.98.0",
      "@tanstack/react-router-with-query": "~1.98.0",
      "@tanstack/zod-adapter": "~1.98.0",
      "@tanstack/valibot-adapter": "~1.98.0",
      "@tanstack/arktype-adapter": "~1.98.0",
      "@tanstack/router-devtools": "~1.98.0",
      "@tanstack/router-cli": "~1.98.0",
      "@tanstack/router-plugin": "~1.98.0",
      "@tanstack/router-vite-plugin": "~1.98.0",
      "@tanstack/start-client": "~1.98.0",
      "@tanstack/start-server": "~1.98.0",
      "@tanstack/create-router": "~1.98.0",
      "@tanstack/create-start": "~1.98.0",
      "@tanstack/start-config": "~1.98.0",
      "@tanstack/start-api-routes": "~1.98.0",
      "@tanstack/start-server-functions-fetcher": "~1.98.0",
      "@tanstack/start-server-functions-handler": "~1.98.0",
      "@tanstack/start-server-functions-client": "~1.98.0",
      "@tanstack/start-server-functions-ssr": "~1.98.0",
      "@tanstack/start-router-manifest": "~1.98.0",
      "@tanstack/start": "~1.98.0"
    }
  }

Just wanted to know if this PR will be enough?

[arfath-linklet]

Does https://github.com/TanStack/router/pull/3318/files resolve this?

[schiller-manuel]

is this still relevant?

[wobsoriano]

Hi @schiller-manuel, I was able to repro this issue with this example of authenticated routes using Clerk SDK - https://github.com/wobsoriano/tanstack-router-3001-repro

[schiller-manuel]

@wobsoriano and would this PR resolve the issue you encountered?

[wobsoriano]

@wobsoriano and would this PR resolve the issue you encountered?

Ignore my comment, looks like the PR is for Start. I just followed this from a different issue and commented here lol sry

[jeffreytgilbert]

Hi @schiller-manuel, I was able to repro this issue with this example of authenticated routes using Clerk SDK - https://github.com/wobsoriano/tanstack-router-3001-repro

I keep seeing this issue in my app with clerk as well. I guess clerk's provider is using useRouter? My routes do, but none of my providers do. And the issue is that we can't make clerk's provider a child of the tanstack router provider, correct? So is the fix in clerk's code or tanstack?