Skip to content
Source
Sign inSign up
TanStack/router

fix(router-plugin): preserve generated route state for aliased HMR imports #7560

Mergedschiller-manuel(GitHub profile, opens in a new tab)merged 2 commits intomain fromrefs/pull/7560/headmerged by schiller-manuel(GitHub profile, opens in a new tab)

fixes #4303

Summary by CodeRabbit

  • Bug Fixes

    • Fixed route HMR behavior to preserve generated route properties when using aliased route imports, ensuring hot reloads maintain route identity, parent relationships, and path information.
  • Tests

    • Added E2E tests for aliased route import hot module reloading.
    • Added unit tests for route export synchronization during HMR updates.
    1. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-plugin

    2. Too much diff to scan? Review this PR in Change Stack to start with the highest-impact changes.

      Review Change Stack

      📝 Walkthrough

      Walkthrough

      This PR fixes hot-reload behavior for TanStack Router routes imported via aliases. Route properties (id, to, path, fullPath) are now synchronized from live routes to newly imported route exports during HMR, enabling aliased route imports to work correctly across hot reloads in both parent and child route components.

      Changes

      Router-plugin HMR aliased import fix

      Layer / File(s)Summary
      Aliased route fixture and route-tree wiring
      e2e/react-start/hmr/src/components/AliasedRouteImportChildPanel.tsx, e2e/react-start/hmr/src/components/AliasedRouteImportParentPanel.tsx, e2e/react-start/hmr/src/routes/aliased-route-imports.$id.tsx, e2e/react-start/hmr/src/routes/aliased-route-imports.$id.child.tsx, e2e/react-start/hmr/src/routeTree.gen.ts
      Introduces two route panel components and corresponding file-based route modules for /aliased-route-imports/$id and child route. Generated route tree is updated with route imports, instances, type registries (FileRoutesByFullPath, FileRoutesByTo, FileRoutesById, FileRouteTypes, RootRouteChildren), and module augmentation for the new routes.
      Core route export synchronization in handleRouteUpdate
      packages/router-plugin/src/core/hmr/handle-route-update.ts
      Extends AnyRouteWithPrivateProps type with parentRoute field. After rebuilding route tree, syncHotRouteExport(oldRoute) copies generated route state (options, parentRoute, _path, _id, _fullPath, _to) from the live route onto the freshly imported route export.
      Vite HMR initial-route reconciliation and snapshot regeneration
      packages/router-plugin/src/core/hmr/vite-adapter.ts, packages/router-plugin/tests/add-hmr/snapshots/react/*, packages/router-plugin/tests/add-hmr/snapshots/solid/*
      Vite adapter derives and persists initialRouteId in hot.data, reconciles against existing router state before hot.accept (applying handleRouteUpdate if needed), and prevents duplicate patching via tsr-route-update-handled guard. Regenerated snapshots (React/Solid) refactor handleRouteUpdate as a reusable shared function, add pre-accept route reconciliation, and apply syncHotRouteExport within the update flow.
      E2E HMR spec fixture registration, timing adjustments, and aliased-navigation test
      e2e/react-start/hmr/tests/app.spec.ts
      Registers aliased route file paths and marker replacements for HMR test fixtures. Increases polling deadlines from 20s to 60s and adjusts internal retry delays (150/500ms → 100ms) to reduce timing flakiness. Adds Playwright test that navigates through aliased parent/child links, applies HMR edits to both route modules, verifies markers reflect updates, and confirms navigation remains correct after HMR.
      HMR logic tests and changeset entry
      packages/router-plugin/tests/add-hmr.test.ts, packages/router-plugin/tests/handle-route-update.test.ts, .changeset/fix-route-hmr-aliased-imports.md
      Adds unit test for generated HMR statement to verify initialRouteId is included and uses nullish-coalescing fallback to hotData. Adds test coverage for handleRouteUpdate route property hydration, ensuring newRoute is populated with id, path, fullPath, to, parentRoute, and options from the live route. Changeset entry documents patch version bump for the HMR aliased-import fix.

      Estimated code review effort

      🎯 3 (Moderate) | ⏱️ ~25 minutes

      • TanStack/router#7422: Both PRs modify the packages/router-plugin/src/core/hmr/handle-route-update.ts HMR path/route-index reconciliation logic (preserving/syncing generated route identity/options and refreshing the route tree) to prevent route mismatches after hot updates.

      Suggested reviewers

      • Sheraff

      Poem

      🐰 A rabbit hops through hot-reload land, Where aliased routes now firmly stand, Once imports broke with every change, Now properties sync through HMR's range, No more lost id, to, or path— Aliased imports found their way back! 🌟

      🚥 Pre-merge checks | ✅ 4 | ❌ 1

      ❌ Failed checks (1 warning)

      Check nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring coverage is 1.75% which is insufficient. The required threshold is 80.00%.Write docstrings for the functions missing them to satisfy the coverage threshold.
      ✅ Passed checks (4 passed)
      Check nameStatusExplanation
      Description Check✅ PassedCheck skipped - CodeRabbit’s high-level summary is enabled.
      Title check✅ PassedThe title clearly describes the main fix: preserving generated route state during HMR for aliased imports.
      Linked Issues check✅ PassedThe PR implements the required fix for issue #4303 by synchronizing route state (id, path, fullPath, to, parentRoute, options) during HMR to preserve aliased import functionality.
      Out of Scope Changes check✅ PassedAll changes are scoped to fix aliased HMR imports: HMR adapter updates, route state synchronization logic, test coverage, and E2E test fixtures for aliased routes.
      ✏️ Tip: You can configure your own custom pre-merge checks in the settings.
      ✨ Finishing Touches
      📝 Generate docstrings
      • Create stacked PR
      • Commit on current branch
      🧪 Generate unit tests (beta)
      • Create PR with unit tests
      • Commit unit tests in branch `fix-4303`

      Comment `@coderabbitai help` to get the list of available commands and usage tips.
    3. View your CI Pipeline Execution ↗ for commit 7cb2f05abb0aecb85a269d71faf513908cd1cc31

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

      💡 Verify your cache is correct by running tasks in a sandbox. Read docs ↗


      ☁️ Nx Cloud last updated this comment at 2026-06-06 08:32:40 UTC

    4. 🚀 Changeset Version Preview

      1 package(s) bumped directly, 6 bumped as dependents.

      🟩 Patch bumps

      PackageVersionReason
      @tanstack/router-plugin1.168.16 → 1.168.17Changeset
      @tanstack/react-start1.168.22 → 1.168.23Dependent
      @tanstack/react-start-rsc0.1.21 → 0.1.22Dependent
      @tanstack/router-vite-plugin1.167.16 → 1.167.17Dependent
      @tanstack/solid-start1.168.22 → 1.168.23Dependent
      @tanstack/start-plugin-core1.171.14 → 1.171.15Dependent
      @tanstack/vue-start1.168.21 → 1.168.22Dependent
    5. Bundle Size Benchmarks

      • Commit: ab9632209474
      • Measured at: 2026-06-06T08:24:04.349Z
      • Baseline source: history:e99e855258e3
      • Dashboard: bundle-size history
      ScenarioCurrent (gzip)Delta vs baselineInitial gzipRawBrotliTrend
      react-router.minimal87.24 KiB0 B (0.00%)87.10 KiB273.72 KiB75.94 KiB█▁▁▁▁▁▁▁▆▆▆
      react-router.full91.02 KiB0 B (0.00%)90.88 KiB286.03 KiB79.16 KiB▂▁▁▁▁▁▁▁███
      solid-router.minimal35.47 KiB0 B (0.00%)35.34 KiB106.02 KiB31.96 KiB█▁▁▁▁▁▁▁▇▇▇
      solid-router.full40.50 KiB0 B (0.00%)40.38 KiB121.16 KiB36.44 KiB▂▁▁▁▁▁▁▁███
      vue-router.minimal52.95 KiB0 B (0.00%)52.82 KiB150.04 KiB47.63 KiB█▁▁▁▁▁▁▁▅▅▅
      vue-router.full58.93 KiB0 B (0.00%)58.80 KiB168.72 KiB52.76 KiB▂▁▁▁▁▁▁▁███
      react-start.minimal101.86 KiB0 B (0.00%)101.72 KiB322.04 KiB88.18 KiB█▁▁▁▁▁▁▁▆▆▆
      react-start.deferred-hydration102.60 KiB0 B (0.00%)101.75 KiB323.42 KiB88.78 KiB█▁▁▁▁▁▁▁▇▇▇
      react-start.full105.25 KiB0 B (0.00%)105.11 KiB332.35 KiB91.09 KiB█▁▁▁▁▁▁▁▇▇▇
      react-start.rsbuild.minimal99.57 KiB0 B (0.00%)99.40 KiB316.51 KiB85.66 KiB█▁▁▁▁▁▁▁▆▆▆
      react-start.rsbuild.minimal-iife99.97 KiB0 B (0.00%)99.80 KiB317.45 KiB85.94 KiB█▁▁▁▁▁▁▁▆▆▆
      react-start.rsbuild.full102.83 KiB0 B (0.00%)102.66 KiB326.91 KiB88.33 KiB█▁▁▁▁▁▁▁▅▅▅
      solid-start.minimal49.58 KiB0 B (0.00%)49.45 KiB152.09 KiB43.77 KiB█▁▁▁▁▁▁▁▇▇▇
      solid-start.deferred-hydration52.84 KiB0 B (0.00%)49.50 KiB160.13 KiB46.76 KiB█▁▁▁▁▁▁▁▇▇▇
      solid-start.full55.36 KiB0 B (0.00%)55.23 KiB169.02 KiB48.79 KiB█▁▁▁▁▁▁▁▆▆▆
      vue-start.minimal70.99 KiB0 B (0.00%)70.87 KiB207.18 KiB62.87 KiB█▁▁▁▁▁▁▁▆▆▆
      vue-start.full74.96 KiB0 B (0.00%)74.83 KiB219.70 KiB66.27 KiB█▁▁▁▁▁▁▁▆▆▆

      Current gzip tracks all emitted client JS chunks. Initial gzip tracks only the entry/import graph. Trend sparkline is historical current gzip ending with this PR measurement; lower is better.

    6. More templates

      @tanstack/arktype-adapter

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

      @tanstack/eslint-plugin-router

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

      @tanstack/eslint-plugin-start

      npm i https://pkg.pr.new/@tanstack/eslint-plugin-start@7560

      @tanstack/history

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

      @tanstack/nitro-v2-vite-plugin

      npm i https://pkg.pr.new/@tanstack/nitro-v2-vite-plugin@7560

      @tanstack/react-router

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

      @tanstack/react-router-devtools

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

      @tanstack/react-router-ssr-query

      npm i https://pkg.pr.new/@tanstack/react-router-ssr-query@7560

      @tanstack/react-start

      npm i https://pkg.pr.new/@tanstack/react-start@7560

      @tanstack/react-start-client

      npm i https://pkg.pr.new/@tanstack/react-start-client@7560

      @tanstack/react-start-rsc

      npm i https://pkg.pr.new/@tanstack/react-start-rsc@7560

      @tanstack/react-start-server

      npm i https://pkg.pr.new/@tanstack/react-start-server@7560

      @tanstack/router-cli

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

      @tanstack/router-core

      npm i https://pkg.pr.new/@tanstack/router-core@7560

      @tanstack/router-devtools

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

      @tanstack/router-devtools-core

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

      @tanstack/router-generator

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

      @tanstack/router-plugin

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

      @tanstack/router-ssr-query-core

      npm i https://pkg.pr.new/@tanstack/router-ssr-query-core@7560

      @tanstack/router-utils

      npm i https://pkg.pr.new/@tanstack/router-utils@7560

      @tanstack/router-vite-plugin

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

      @tanstack/solid-router

      npm i https://pkg.pr.new/@tanstack/solid-router@7560

      @tanstack/solid-router-devtools

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

      @tanstack/solid-router-ssr-query

      npm i https://pkg.pr.new/@tanstack/solid-router-ssr-query@7560

      @tanstack/solid-start

      npm i https://pkg.pr.new/@tanstack/solid-start@7560

      @tanstack/solid-start-client

      npm i https://pkg.pr.new/@tanstack/solid-start-client@7560

      @tanstack/solid-start-server

      npm i https://pkg.pr.new/@tanstack/solid-start-server@7560

      @tanstack/start-client-core

      npm i https://pkg.pr.new/@tanstack/start-client-core@7560

      @tanstack/start-fn-stubs

      npm i https://pkg.pr.new/@tanstack/start-fn-stubs@7560

      @tanstack/start-plugin-core

      npm i https://pkg.pr.new/@tanstack/start-plugin-core@7560

      @tanstack/start-server-core

      npm i https://pkg.pr.new/@tanstack/start-server-core@7560

      @tanstack/start-static-server-functions

      npm i https://pkg.pr.new/@tanstack/start-static-server-functions@7560

      @tanstack/start-storage-context

      npm i https://pkg.pr.new/@tanstack/start-storage-context@7560

      @tanstack/valibot-adapter

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

      @tanstack/virtual-file-routes

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

      @tanstack/vue-router

      npm i https://pkg.pr.new/@tanstack/vue-router@7560

      @tanstack/vue-router-devtools

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

      @tanstack/vue-router-ssr-query

      npm i https://pkg.pr.new/@tanstack/vue-router-ssr-query@7560

      @tanstack/vue-start

      npm i https://pkg.pr.new/@tanstack/vue-start@7560

      @tanstack/vue-start-client

      npm i https://pkg.pr.new/@tanstack/vue-start-client@7560

      @tanstack/vue-start-server

      npm i https://pkg.pr.new/@tanstack/vue-start-server@7560

      @tanstack/zod-adapter

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

      commit: 83e7c8d

    7. Actionable comments posted: 1

      🤖 Prompt for all review comments with AI agents
      Verify each finding against current code. Fix only still-valid issues, skip the
      rest with a brief reason, keep changes minimal, and validate.
      
      Inline comments:
      In `@e2e/react-start/hmr/tests/app.spec.ts`:
      - Around line 30-31: The new editable aliased route panels
      (aliasedRouteImportParentPanel and aliasedRouteImportChildPanel) lack entries in
      the routeFileRestoreChecks map so waitForRestoredRouteFile returns immediately;
      add routeFileRestoreChecks entries for both aliasedRouteImportParentPanel and
      aliasedRouteImportChildPanel that point to their component file paths
      (components/AliasedRouteImportParentPanel.tsx and
      components/AliasedRouteImportChildPanel.tsx) and provide appropriate
      content/match checks (the same style used by other entries) so
      waitForRestoredRouteFile blocks until HMR restore is observed.
      🪄 Autofix (Beta)

      Fix all unresolved CodeRabbit comments on this PR:

      • Push a commit to this branch (recommended)
      • Create a new PR with the fixes

      ℹ️ Review info
      ⚙️ Run configuration

      Configuration used: defaults

      Review profile: CHILL

      Plan: Pro

      Run ID: 0e497855-910d-40d8-bc3f-c85aaf87f835

      📥 Commits

      Reviewing files that changed from the base of the PR and between e99e855258e3350832b7b09a637af8f9d417f1b9 and 83e7c8d927152e4ba2698643c5610a2969e422ed.

      📒 Files selected for processing (21)
      • .changeset/fix-route-hmr-aliased-imports.md
      • e2e/react-start/hmr/src/components/AliasedRouteImportChildPanel.tsx
      • e2e/react-start/hmr/src/components/AliasedRouteImportParentPanel.tsx
      • e2e/react-start/hmr/src/routeTree.gen.ts
      • e2e/react-start/hmr/src/routes/aliased-route-imports.$id.child.tsx
      • e2e/react-start/hmr/src/routes/aliased-route-imports.$id.tsx
      • e2e/react-start/hmr/tests/app.spec.ts
      • packages/router-plugin/src/core/hmr/handle-route-update.ts
      • 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/arrow-function@webpack-hot.tsx
      • packages/router-plugin/tests/add-hmr/snapshots/react/createRootRoute-inline-component@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
      • packages/router-plugin/tests/handle-route-update.test.ts
      e2e/react-start/hmr/tests/app.spec.ts lines 30 to 31
      @@ -27,3 +27,5 @@
      2727 componentHmrNamedNosplit: 'routes/component-hmr-named-nosplit.tsx',
      2828 componentHmrInlineErrorSplit: 'routes/component-hmr-inline-error-split.tsx',
      2929 componentHmrNamedErrorSplit: 'routes/component-hmr-named-error-split.tsx',
      30+ aliasedRouteImportParentPanel: 'components/AliasedRouteImportParentPanel.tsx',
      31+ aliasedRouteImportChildPanel: 'components/AliasedRouteImportChildPanel.tsx',

      ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

      Add restore checks for the new aliased route panel files.

      aliasedRouteImportParentPanel and aliasedRouteImportChildPanel are now editable/restored, but they have no routeFileRestoreChecks entries. That makes waitForRestoredRouteFile return early for these keys, so subsequent tests can run before restore HMR settles.

      Suggested patch
       const routeFileRestoreChecks: Partial<
         Record<
           RouteFileKey,
           {
             url: string
             testId: string
             text: string
             assert?: (page: Page) => Promise<void>
           }
         >
       > = {
      +  aliasedRouteImportParentPanel: {
      +    url: '/aliased-route-imports/A',
      +    testId: 'aliased-parent-marker',
      +    text: 'aliased-parent-baseline',
      +  },
      +  aliasedRouteImportChildPanel: {
      +    url: '/aliased-route-imports/A/child',
      +    testId: 'aliased-child-marker',
      +    text: 'aliased-child-baseline',
      +  },
         index: {
           url: '/',
           testId: 'marker',
           text: 'baseline',

      Also applies to: 229-236

      🤖 Prompt for AI Agents
      Verify each finding against current code. Fix only still-valid issues, skip the
      rest with a brief reason, keep changes minimal, and validate.
      
      In `@e2e/react-start/hmr/tests/app.spec.ts` around lines 30 - 31, The new editable
      aliased route panels (aliasedRouteImportParentPanel and
      aliasedRouteImportChildPanel) lack entries in the routeFileRestoreChecks map so
      waitForRestoredRouteFile returns immediately; add routeFileRestoreChecks entries
      for both aliasedRouteImportParentPanel and aliasedRouteImportChildPanel that
      point to their component file paths
      (components/AliasedRouteImportParentPanel.tsx and
      components/AliasedRouteImportChildPanel.tsx) and provide appropriate
      content/match checks (the same style used by other entries) so
      waitForRestoredRouteFile blocks until HMR restore is observed.
    8. Merging this PR will not alter performance

      ✅ 5 untouched benchmarks ⏩ 1 skipped benchmark1


      Comparing fix-4303 (83e7c8d) with main (e99e855) Open in CodSpeed

      Footnotes

      1. 1 benchmark was skipped, so the baseline result was used instead. If it was deleted from the codebase, click here and archive it to remove it from the performance reports. ↩

Sign in to join this conversation.