fix(router-core): the server's route tree cache follows a re-evaluated route tree #8862
main fromrefs/pull/8862/head·opened The bug#
On the server, RouterCore.update shares one processed route tree across requests through globalThis.__TSR_CACHE__ whenever NODE_ENV isn't development. Main keys that cache by the routeTree object.
A dev server whose NODE_ENV isn't development re-evaluates the route tree module after an edit. Examples are NODE_ENV=production vite dev, or a dev server under test. The root route is an unchanged module's export, so it's the same object; the re-evaluated module only gives it new children. The cache key still matches, so the server keeps matching the routes from before the edit.
The fix#
Key the cache by routeTree.children instead. Both addChildren and the generated _addFileChildren assign a new array on every call, so a re-evaluated route tree misses the cache. A root without children never reads the cache, so two different childless roots don't share one entry.
The isServer ?? this.isServer checks stay inline in both branch conditions. The client bundles are byte-identical, because those branches are dead code on the client.
This change comes from #8817, which is being split into smaller PRs. The router.ts hunk, the test file and the changeset are identical to #8817's.
Tests#
packages/router-core/tests/route-tree-caches.test.ts gets #8817's 2 new tests:
- "a server router reads the routes a re-evaluated route tree gave the same root". It fails on main: the second router matches the route from before the edit.
- "a server router never reads the cache of another route tree without children". It passes on main too. It guards the new
children &&check.
Both tests use createTestRouter, getMatchedRoutes and routesById only.
Validation#
Node 26.12.1; every target ran through Nx.
@tanstack/router-core:test:unit(3653 passed),test:types,test:eslintandtest:buildall pass.test:unitpasses for@tanstack/react-router(1240),@tanstack/solid-router(1030) and@tanstack/vue-router(1020). None of them reads__TSR_CACHE__.tanstack-react-start-e2e-basic:test:e2e--vite-ssrandtest:e2e--rsbuild-ssreach pass 139 tests.- Start SSR benchmark (
@benchmarks/ssr:test:perf:react, 34 benches, same workload): I ran baseline and candidate twice each, in the order C, B, B, C. Comparing the best p50 of each side, the geomean is −1.5%, and no bench is slower by more than 1.4%. That's within run-to-run noise: the two baseline runs differed by up to 22%. The change is neutral. - Bundle size (full run, all 18 scenarios): +0 B gzip, raw and brotli everywhere. The emitted client JS is byte-identical; only the Rsbuild scenarios' server bundles differ.
Against #8817#
I merged #8817's head (5bc674ea80) on top of this branch with git merge-tree. It gives the same 19 conflicted files as merging #8817 into main alone, so this PR adds no new conflicts. router.ts, the test file and the changeset merge to exactly #8817's content.
After this lands, #8817 drops .changeset/router-core-server-route-tree-cache-edits.md and this router.ts hunk from its diff. Both are already on main, so nothing in #8817 needs editing by hand. #8817's description doesn't mention this fix.
🤖 Generated with Claude Code
Summary by CodeRabbit#
- Bug Fixes
- Fixed a server-side route caching issue so updated routes are reflected after route edits, including when the root route is reused.
- Fixed route handling for routers created with a distinct root that has no children.
- 1
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-core
No actionable comments were generated in the recent review.
Walkthrough
-
The server route-tree cache now identifies entries by the root route’s
childrenreference instead of the root route object. Tests cover routers created after child replacement and routers created with distinct childless roots.Changes: Route-tree cache
Layer / File(s) Summary Cache matching and validation
packages/router-core/src/router.ts,packages/router-core/tests/route-tree-caches.test.ts,.changeset/router-core-server-route-tree-cache-edits.mdCache entries store and compare root childrenreferences. Server tests cover replacement children and distinct childless roots. A patch changeset describes the update.Estimated code review effort: 2 (Simple) | ~10 minutes
Change: Bug fix
Suggested reviewers:
schiller-manuel
Merge Risk:
Low · up toec5f4-
Route edits remain correct, but subsequent server routers may incur repeated route-tree rebuilds until restart; this is a bounded performance regression.
Pre-merge checks:
5-
Check name Status Explanation Title check The title clearly describes the main change: updating the server route-tree cache to follow a re-evaluated route tree. Description check The description explains the bug, fix, tests, validation results, release changeset context, and AI assistance. It does not use the template headings or include the checklist and release-impact checkb… Docstring Coverage No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat… Linked Issues check Check skipped because no linked issues were found for this pull request. Out of Scope Changes check Check skipped because no linked issues were found for this pull request. Full details: Description check
-
Explanation
The description explains the bug, fix, tests, validation results, release changeset context, and AI assistance. It does not use the template headings or include the checklist and release-impact checkboxes, but the required change and validation information are substantially complete.
Full details: Docstring Coverage
-
Explanation
No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 2 files. (1 skipped: 1 unsupported.)
-
Finishing Touches
-
Generate docstrings
-
- Commit to this branch
- Create a new PR
Generate unit tests (beta)
-
- Commit to this branch
- Create a new PR
-
- Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
CodeRabbit Verify#
- Run CodeRabbit Verify to test the changes in this pull request.
Recent review info-
Run configuration-
- Source mode: Auto
- Repository: TanStack/router
- Branch: router-core/server-route-tree-cache
- File: .coderabbit.yaml
- Commit: ec5f496
- Layers: Repository YAML
- Review profile: CHILL
- Plan: Advanced
- Run ID:
cbcaf940-55d5-4ecc-9e9f-19a7e4428d75
Commits-
Reviewing files that changed from the base of the PR and between ad5b3b7a0990eed7351d672ea6695d341108e0d6 and ec5f496fc29ba8563af1cdb1de01a353f42dd136.
Files selected for processing: 3-
.changeset/router-core-server-route-tree-cache-edits.mdpackages/router-core/src/router.tspackages/router-core/tests/route-tree-caches.test.ts
Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 6 remain after this review.
-
-
🚀 Changeset Version Preview#
5 package(s) bumped directly, 19 bumped as dependents.
🟨 Minor bumps#
Package Version Reason @tanstack/router-cli1.167.46 → 1.168.0 Changeset @tanstack/router-generator1.167.46 → 1.168.0 Changeset @tanstack/router-plugin1.168.48 → 1.169.0 Changeset @tanstack/router-utils1.162.4 → 1.163.0 Changeset 🟩 Patch bumps#
Package Version Reason @tanstack/router-core1.171.39 → 1.171.40 Changeset @tanstack/react-router1.170.46 → 1.170.47 Dependent @tanstack/react-start1.169.4 → 1.169.5 Dependent @tanstack/react-start-client1.168.44 → 1.168.45 Dependent @tanstack/react-start-rsc0.1.65 → 0.1.66 Dependent @tanstack/react-start-server1.167.52 → 1.167.53 Dependent @tanstack/router-vite-plugin1.167.48 → 1.167.49 Dependent @tanstack/solid-router1.170.43 → 1.170.44 Dependent @tanstack/solid-start1.169.4 → 1.169.5 Dependent @tanstack/solid-start-client1.168.42 → 1.168.43 Dependent @tanstack/solid-start-server1.167.50 → 1.167.51 Dependent @tanstack/start-client-core1.170.39 → 1.170.40 Dependent @tanstack/start-plugin-core1.171.55 → 1.171.56 Dependent @tanstack/start-server-core1.169.45 → 1.169.46 Dependent @tanstack/start-static-server-functions1.167.44 → 1.167.45 Dependent @tanstack/start-storage-context1.167.41 → 1.167.42 Dependent @tanstack/vue-router1.170.42 → 1.170.43 Dependent @tanstack/vue-start1.169.4 → 1.169.5 Dependent @tanstack/vue-start-client1.167.45 → 1.167.46 Dependent @tanstack/vue-start-server1.167.50 → 1.167.51 Dependent View your CI Pipeline Execution ↗ for commit ec5f496fc29ba8563af1cdb1de01a353f42dd136
Command Status Duration Result nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded 9m 55s View ↗ nx run-many --target=build --exclude=examples/*...✅ Succeeded 1m 32s View ↗
☁️ Nx Cloud last updated this comment at
2026-11-03 20:04:40UTCBundle Size Benchmarks#
This pull request does not affect bundle size in any measured scenario.
More templates
- tanstack-router-react-example-authenticated-routes
- tanstack-router-react-example-authenticated-routes-firebase
- tanstack-router-react-example-basic
- tanstack-router-react-example-basic-default-search-params
- tanstack-router-react-example-basic-devtools-panel
- tanstack-router-react-example-basic-file-based
- tanstack-router-react-example-basic-non-nested-devtools
- 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-i18n-paraglide
- 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
- router-mono-simple-lazy
- tanstack-router-react-example-scroll-restoration
- tanstack-search-validator-adapters
- tanstack-start-example-bare
- tanstack-start-example-basic
- tanstack-start-example-basic-auth
- tanstack-router-react-example-basic-authjs
- tanstack-start-example-basic-cloudflare
- tanstack-start-example-basic-react-query
- tanstack-start-example-basic-rsbuild
- tanstack-start-example-basic-static
- tanstack-start-bun-hosting
- tanstack-start-example-clerk-basic
- tanstack-start-example-convex-trellaux
- tanstack-start-example-counter
- tanstack-start-i18n-paraglide
- tanstack-start-example-large
- tanstack-start-example-material-ui
- tanstack-start-example-next-migration
- tanstack-start-example-rscs
- tanstack-start-streaming-data-from-server-functions
- tanstack-start-example-supabase-basic
- tanstack-start-tailwind-v4
- tanstack-start-example-trellaux
- tanstack-start-example-workos
- tanstack-router-react-example-view-transitions
- tanstack-router-react-example-with-framer-motion
- tanstack-router-react-example-with-trpc
- tanstack-router-react-example-with-trpc-react-query
- tanstack-router-vue-example-basic-jsx
- tanstack-router-vue-example-basic-file-based-jsx
- tanstack-router-vue-example-basic-file-based-sfc
- tanstack-router-solid-example-authenticated-routes
- tanstack-router-solid-example-authenticated-routes-firebase
- tanstack-router-solid-example-basic
- tanstack-router-solid-example-basic-default-search-params
- tanstack-router-solid-example-basic-devtools-panel
- tanstack-router-solid-example-basic-file-based
- tanstack-router-solid-example-basic-non-nested-devtools
- tanstack-router-solid-example-basic-solid-query
- tanstack-router-solid-example-basic-solid-query-file-based
- tanstack-router-solid-example-basic-ssr-file-based
- tanstack-router-solid-example-basic-ssr-streaming-file-based
- tanstack-router-solid-example-basic-virtual-file-based
- tanstack-router-solid-example-basic-virtual-inside-file-based
- tanstack-router-solid-example-deferred-data
- tanstack-router-solid-i18n-paraglide
- tanstack-router-solid-example-kitchen-sink
- tanstack-router-solid-example-kitchen-sink-file-based
- tanstack-router-solid-example-kitchen-sink-solid-query
- tanstack-router-solid-example-kitchen-sink-solid-query-file-based
- tanstack-router-solid-example-large-file-based
- tanstack-router-solid-example-location-masking
- tanstack-router-solid-example-navigation-blocking
- tanstack-router-solid-example-quickstart
- tanstack-router-solid-example-quickstart-esbuild-file-based
- tanstack-router-solid-example-quickstart-file-based
- tanstack-router-solid-example-quickstart-rspack-file-based
- tanstack-router-solid-example-quickstart-webpack-file-based
- @tanstack/router-solid-mono-simple
- router-solid-mono-simple-lazy
- router-solid-monorepo-solid-query
- tanstack-router-solid-example-scroll-restoration
- tanstack-solid-router-search-validator-adapters
- tanstack-solid-start-example-basic
- tanstack-solid-start-example-basic-auth
- tanstack-solid-start-example-basic-authjs
- tanstack-solid-start-example-basic-cloudflare
- tanstack-solid-start-example-basic-netlify
- tanstack-solid-start-example-basic-nitro
- tanstack-start-example-basic-solid-query
- tanstack-solid-start-example-basic-static
- tanstack-solid-start-bun-hosting
- tanstack-solid-start-example-convex-better-auth
- tanstack-solid-start-example-counter
- tanstack-solid-start-i18n-paraglide
- tanstack-solid-start-example-large
- tanstack-solid-start-streaming-data-from-server-functions
- tanstack-solid-start-example-supabase-basic
- tanstack-solid-start-tailwind-v4
- tanstack-router-solid-example-view-transitions
- tanstack-router-solid-example-with-framer-motion
- tanstack-router-solid-example-with-trpc
@tanstack/arktype-adapter
npm i https://pkg.pr.new/@tanstack/arktype-adapter@8862@tanstack/eslint-plugin-router
npm i https://pkg.pr.new/@tanstack/eslint-plugin-router@8862@tanstack/eslint-plugin-start
npm i https://pkg.pr.new/@tanstack/eslint-plugin-start@8862@tanstack/history
npm i https://pkg.pr.new/@tanstack/history@8862@tanstack/react-router
npm i https://pkg.pr.new/@tanstack/react-router@8862@tanstack/react-router-devtools
npm i https://pkg.pr.new/@tanstack/react-router-devtools@8862@tanstack/react-router-ssr-query
npm i https://pkg.pr.new/@tanstack/react-router-ssr-query@8862@tanstack/react-start
npm i https://pkg.pr.new/@tanstack/react-start@8862@tanstack/react-start-client
npm i https://pkg.pr.new/@tanstack/react-start-client@8862@tanstack/react-start-rsc
npm i https://pkg.pr.new/@tanstack/react-start-rsc@8862@tanstack/react-start-server
npm i https://pkg.pr.new/@tanstack/react-start-server@8862@tanstack/router-cli
npm i https://pkg.pr.new/@tanstack/router-cli@8862@tanstack/router-core
npm i https://pkg.pr.new/@tanstack/router-core@8862@tanstack/router-devtools
npm i https://pkg.pr.new/@tanstack/router-devtools@8862@tanstack/router-devtools-core
npm i https://pkg.pr.new/@tanstack/router-devtools-core@8862@tanstack/router-generator
npm i https://pkg.pr.new/@tanstack/router-generator@8862@tanstack/router-plugin
npm i https://pkg.pr.new/@tanstack/router-plugin@8862@tanstack/router-ssr-query-core
npm i https://pkg.pr.new/@tanstack/router-ssr-query-core@8862@tanstack/router-utils
npm i https://pkg.pr.new/@tanstack/router-utils@8862@tanstack/router-vite-plugin
npm i https://pkg.pr.new/@tanstack/router-vite-plugin@8862@tanstack/solid-router
npm i https://pkg.pr.new/@tanstack/solid-router@8862@tanstack/solid-router-devtools
npm i https://pkg.pr.new/@tanstack/solid-router-devtools@8862@tanstack/solid-router-ssr-query
npm i https://pkg.pr.new/@tanstack/solid-router-ssr-query@8862@tanstack/solid-start
npm i https://pkg.pr.new/@tanstack/solid-start@8862@tanstack/solid-start-client
npm i https://pkg.pr.new/@tanstack/solid-start-client@8862@tanstack/solid-start-server
npm i https://pkg.pr.new/@tanstack/solid-start-server@8862@tanstack/start-client-core
npm i https://pkg.pr.new/@tanstack/start-client-core@8862@tanstack/start-fn-stubs
npm i https://pkg.pr.new/@tanstack/start-fn-stubs@8862@tanstack/start-plugin-core
npm i https://pkg.pr.new/@tanstack/start-plugin-core@8862@tanstack/start-server-core
npm i https://pkg.pr.new/@tanstack/start-server-core@8862@tanstack/start-static-server-functions
npm i https://pkg.pr.new/@tanstack/start-static-server-functions@8862@tanstack/start-storage-context
npm i https://pkg.pr.new/@tanstack/start-storage-context@8862@tanstack/valibot-adapter
npm i https://pkg.pr.new/@tanstack/valibot-adapter@8862@tanstack/virtual-file-routes
npm i https://pkg.pr.new/@tanstack/virtual-file-routes@8862@tanstack/vue-router
npm i https://pkg.pr.new/@tanstack/vue-router@8862@tanstack/vue-router-devtools
npm i https://pkg.pr.new/@tanstack/vue-router-devtools@8862@tanstack/vue-router-ssr-query
npm i https://pkg.pr.new/@tanstack/vue-router-ssr-query@8862@tanstack/vue-start
npm i https://pkg.pr.new/@tanstack/vue-start@8862@tanstack/vue-start-client
npm i https://pkg.pr.new/@tanstack/vue-start-client@8862@tanstack/vue-start-server
npm i https://pkg.pr.new/@tanstack/vue-start-server@8862@tanstack/zod-adapter
npm i https://pkg.pr.new/@tanstack/zod-adapter@8862commit:
ec5f496Closing: a dev server running with a NODE_ENV other than development (e.g.
NODE_ENV=production vite dev) isn't a supported setup, so this case doesn't need handling. #8817 will drop its version of this change too.Sheraff(GitHub profile, opens in a new tab) closed this
Merging this PR will not alter performance#
1 warning
:warning: 56 benchmarks are dominated by system calls
System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.
✅ 194untouched benchmarks⏩ 3skipped benchmarks1
Comparingrouter-core/server-route-tree-cache(ec5f496) withmain(ad5b3b7)Footnotes#
-
3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩
-
Sign in to join this conversation.
🦋 Changeset detected#
Latest commit: ec5f496fc29ba8563af1cdb1de01a353f42dd136
The changes in this PR will be included in the next version bump.
This PR includes changesets to release 23 packages
Not sure what this means? Click here to learn what changesets are.
Click here if you're a maintainer who wants to add another changeset to this PR