Skip to content
Source
Sign inSign up
TanStack/router

fix(router-plugin): don't patch foreign routers on first route-module import #7937

ClosedFrancoKaddour(GitHub profile, opens in a new tab)wants to merge 1 commit intomain fromrefs/pull/7937/headopened

Closes #7921

Problem

Since @tanstack/router-plugin@1.168.17 (837897f, #7560), the injected Vite HMR preamble eagerly calls handleRouteUpdate during the initial evaluation of every route module whenever window.__TSR_ROUTER__ already owns a route with the same id but a different object identity.

That heuristic assumes "same id + different identity ⇒ re-imported copy of this file". With multiple routers in one window (module federation host/remote, microfrontends), route ids like __root__ and / collide between apps, and window.__TSR_ROUTER__ points at whichever router was created last. The remote's route modules then patch the host's router: the host's route options are overwritten, preserveComponentIdentity grafts the host's components onto the remote's route options, and syncHotRouteExport rewrites the remote's Route export (parentRoute, _id, _path, …) with the host's tree state. Since each app ships its own React copy in dev, rendering the remote's router executes components bound to the host's React → "Invalid hook call". Creating the host router is enough to trigger it — no rendering needed.

Fix

Vite's hot.data persists across re-evaluations of a module but starts empty on first import — exactly the missing discriminator. The eager patch (only needed for the #4303 aliased-import re-evaluation case) is now gated behind a tsr-route-initialized flag in hot.data, restoring the pre-1.168.17 behavior for first imports while keeping the #4303 fix intact.

Note: the hot.accept path has always resolved window.__TSR_ROUTER__ (pre-1.168.17), so editing a route file while a foreign router was created last can still target the wrong router. That's a pre-existing, edit-time-only limitation; properly scoping the global to a per-router registry is left as a follow-up if maintainers want it.

Summary by CodeRabbit

  • Bug Fixes

    • Improved Vite hot-module reloading to prevent route conflicts during initial application loads.
    • Prevented routes from separate router instances from being incorrectly merged or updated.
    • Ensured existing routes are only reused during genuine hot re-evaluations.
  • Tests

    • Added coverage for route initialization and hot re-evaluation behavior across supported route patterns and frameworks.
    1. Review Change Stack

      No actionable comments were generated in the recent review. 🎉

      ℹ️ Recent review info
      ⚙️ Run configuration

      Configuration used: defaults

      Review profile: CHILL

      Plan: Pro Plus

      Run ID: b6e35740-f615-4f49-80f7-05b24d771220

      📥 Commits

      Reviewing files that changed from the base of the PR and between 2cb221cfd3b95f55498b22e76e9ac96a32cd26d4 and cb44f0c7fdc97eeb304de0e0b0e32b0bfaa66c45.

      📒 Files selected for processing (14)
      • .changeset/fix-multi-router-first-import.md
      • packages/router-plugin/src/core/hmr/vite-adapter.ts
      • packages/router-plugin/tests/add-hmr.test.ts
      • packages/router-plugin/tests/add-hmr/snapshots/react/arrow-function@true.tsx
      • packages/router-plugin/tests/add-hmr/snapshots/react/createFileRoute-lowercase-components@true.tsx
      • packages/router-plugin/tests/add-hmr/snapshots/react/createRootRoute-inline-component@true.tsx
      • packages/router-plugin/tests/add-hmr/snapshots/react/createRootRoute-lowercase-components@true.tsx
      • packages/router-plugin/tests/add-hmr/snapshots/react/createRootRoute@true.tsx
      • packages/router-plugin/tests/add-hmr/snapshots/react/createRootRouteWithContext-type-args@true.tsx
      • packages/router-plugin/tests/add-hmr/snapshots/react/explicit-undefined-component@true.tsx
      • packages/router-plugin/tests/add-hmr/snapshots/react/function-declaration@true.tsx
      • packages/router-plugin/tests/add-hmr/snapshots/react/multi-component@true.tsx
      • packages/router-plugin/tests/add-hmr/snapshots/react/string-literal-keys@true.tsx
      • packages/router-plugin/tests/add-hmr/snapshots/solid/arrow-function@true.tsx

      📝 Walkthrough

      Walkthrough

      Changes

      HMR route initialization

      Layer / File(s)Summary
      Gate eager route patching
      packages/router-plugin/src/core/hmr/vite-adapter.ts, .changeset/fix-multi-router-first-import.md
      The Vite adapter stores tsr-route-initialized in hot data and looks up existing routes only after prior initialization.
      Update generated HMR output and coverage
      packages/router-plugin/tests/add-hmr.test.ts, packages/router-plugin/tests/add-hmr/snapshots/{react,solid}/*
      Tests and snapshots verify initialization tracking and hot-reevaluation gating across route module patterns.

      Estimated code review effort: 2 (Simple) | ~10 minutes

      Suggested labels: package: router-plugin

      Suggested reviewers: schiller-manuel, sheraff

      🚥 Pre-merge checks | ✅ 5
      ✅ Passed checks (5 passed)
      Check nameStatusExplanation
      Description Check✅ PassedCheck skipped - CodeRabbit’s high-level summary is enabled.
      Title check✅ PassedThe title clearly summarizes the fix that prevents foreign routers from being patched during the first route-module import.
      Linked Issues check✅ PassedThe changes gate initial HMR route patching and preserve re-evaluation behavior, directly addressing issue #7921.
      Out of Scope Changes check✅ PassedAll changes support the router-plugin fix, including implementation, tests, snapshots, and the release changeset.
      Docstring Coverage✅ PassedNo functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
      ✨ Finishing Touches
      🧪 Generate unit tests (beta)
      • Create PR with unit tests

      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
      Comment `@coderabbitai help` to get the list of available commands.
    2. Superseded by #8277, which builds on this contribution and consolidates the related HMR and missing-chunk recovery fixes. Contributor credit is preserved in the replacement.

Sign in to join this conversation.