Skip to content
Source
Sign inSign up
TanStack/router

fix(router-core): the server's route tree cache follows a re-evaluated route tree #8862

ClosedSheraff(GitHub profile, opens in a new tab)wants to merge 2 commits intomain fromrefs/pull/8862/headopened

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:eslint and test:build all pass.
  • test:unit passes 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-ssr and test:e2e--rsbuild-ssr each 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. 🦋 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
      NameType
      @tanstack/router-corePatch
      @tanstack/react-routerPatch
      @tanstack/react-start-clientPatch
      @tanstack/react-start-rscPatch
      @tanstack/react-start-serverPatch
      @tanstack/router-generatorPatch
      @tanstack/router-pluginPatch
      @tanstack/solid-routerPatch
      @tanstack/solid-start-clientPatch
      @tanstack/solid-start-serverPatch
      @tanstack/start-client-corePatch
      @tanstack/start-plugin-corePatch
      @tanstack/start-server-corePatch
      @tanstack/start-storage-contextPatch
      @tanstack/vue-routerPatch
      @tanstack/vue-start-clientPatch
      @tanstack/vue-start-serverPatch
      @tanstack/react-startPatch
      @tanstack/router-cliPatch
      @tanstack/router-vite-pluginPatch
      @tanstack/solid-startPatch
      @tanstack/start-static-server-functionsPatch
      @tanstack/vue-startPatch

      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

    2. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-core

    3. Review in Change Stack →

      No actionable comments were generated in the recent review.

      Walkthrough

      The server route-tree cache now identifies entries by the root route’s children reference 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.md
      Cache entries store and compare root children references. 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 to ec5f4

      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: Passed 5
      Check nameStatusExplanation
      Title checkPassedThe title clearly describes the main change: updating the server route-tree cache to follow a re-evaluated route tree.
      Description checkPassedThe 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 CoveragePassedNo 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 checkPassedCheck skipped because no linked issues were found for this pull request.
      Out of Scope Changes checkPassedCheck 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.

      Share

      CodeRabbit Verify

      • Run CodeRabbit Verify to test the changes in this pull request.
      Recent review info
      Run configuration
      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.md
      • packages/router-core/src/router.ts
      • packages/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.

    4. 🚀 Changeset Version Preview

      5 package(s) bumped directly, 19 bumped as dependents.

      🟨 Minor bumps

      PackageVersionReason
      @tanstack/router-cli1.167.46 → 1.168.0Changeset
      @tanstack/router-generator1.167.46 → 1.168.0Changeset
      @tanstack/router-plugin1.168.48 → 1.169.0Changeset
      @tanstack/router-utils1.162.4 → 1.163.0Changeset

      🟩 Patch bumps

      PackageVersionReason
      @tanstack/router-core1.171.39 → 1.171.40Changeset
      @tanstack/react-router1.170.46 → 1.170.47Dependent
      @tanstack/react-start1.169.4 → 1.169.5Dependent
      @tanstack/react-start-client1.168.44 → 1.168.45Dependent
      @tanstack/react-start-rsc0.1.65 → 0.1.66Dependent
      @tanstack/react-start-server1.167.52 → 1.167.53Dependent
      @tanstack/router-vite-plugin1.167.48 → 1.167.49Dependent
      @tanstack/solid-router1.170.43 → 1.170.44Dependent
      @tanstack/solid-start1.169.4 → 1.169.5Dependent
      @tanstack/solid-start-client1.168.42 → 1.168.43Dependent
      @tanstack/solid-start-server1.167.50 → 1.167.51Dependent
      @tanstack/start-client-core1.170.39 → 1.170.40Dependent
      @tanstack/start-plugin-core1.171.55 → 1.171.56Dependent
      @tanstack/start-server-core1.169.45 → 1.169.46Dependent
      @tanstack/start-static-server-functions1.167.44 → 1.167.45Dependent
      @tanstack/start-storage-context1.167.41 → 1.167.42Dependent
      @tanstack/vue-router1.170.42 → 1.170.43Dependent
      @tanstack/vue-start1.169.4 → 1.169.5Dependent
      @tanstack/vue-start-client1.167.45 → 1.167.46Dependent
      @tanstack/vue-start-server1.167.50 → 1.167.51Dependent
    5. View your CI Pipeline Execution ↗ for commit ec5f496fc29ba8563af1cdb1de01a353f42dd136

      CommandStatusDurationResult
      nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded9m 55sView ↗
      nx run-many --target=build --exclude=examples/*...✅ Succeeded1m 32sView ↗

      ☁️ Nx Cloud last updated this comment at 2026-11-03 20:04:40 UTC

    6. Bundle Size Benchmarks

      This pull request does not affect bundle size in any measured scenario.

    7. More templates

      @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@8862

      commit: ec5f496

    8. Closing: 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.

    9. 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.

      Learn more about system calls

      See affected benchmarks

      ✅ 194 untouched benchmarks ⏩ 3 skipped benchmarks1


      Comparing router-core/server-route-tree-cache (ec5f496) with main (ad5b3b7) Open in CodSpeed

      Footnotes

      1. 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.