Skip to content
Source
Sign inSign up
TanStack/router

refactor(router-plugin): remove `plugin.hmr.style` and `HmrOptions` #8856

MergedSheraff(GitHub profile, opens in a new tab)merged 1 commit intomain fromrefs/pull/8856/headmerged by Sheraff(GitHub profile, opens in a new tab)

Split out of #8817 to make that PR smaller. config.ts and index.ts get the same changes #8817 makes. #8817 rewrites or deletes the other files touched here, so a rebase only needs to keep #8817's versions of them.

Why

plugin.hmr.style ('vite' | 'webpack') was undocumented and never useful to set yourself:

  • The webpack and Rspack entries overwrote whatever you passed with 'webpack'.
  • On Vite, 'webpack' emitted import.meta.webpackHot, so route HMR stopped working without any error.

The changeset is a patch, like #8853: the option was undocumented, and nobody could use it to get anything except the default.

Changes

  • plugin.hmr is removed from the config schema, and the HmrOptions type is no longer exported from @tanstack/router-plugin.
  • The HMR style is now an internal parameter. createRouterCodeSplitterPlugin and createRouterHmrPlugin take it as an argument, with 'vite' as the default:
    • the composed plugin (tanstackRouter) picks it from the bundler unplugin reports (webpack/rspack → 'webpack');
    • the standalone TanStackRouterCodeSplitter{Webpack,Rspack} entries pass 'webpack'.
  • The internal HmrStyle type moves from core/config.ts to core/hmr.
  • tanstackRouter from /webpack and /rspack now passes unpluginRouterComposedFactory to unplugin directly, so its options parameter has the Vite entry's type (Partial<Config | (() => Config)>) instead of unknown. That type still accepts every value except null.
  • Tests: the webpack route-HMR test in code-splitter-plugin-pipeline.test.ts now passes the style through the test helper instead of plugin.hmr.style.

Nothing in packages/, examples/, e2e/ or docs/ used the option. This only changes build-time plugin code, so no client bundle changes.

Validation

  • @tanstack/router-plugin: test:unit, test:types, test:eslint and test:build pass. @tanstack/start-plugin-core: test:unit and test:types pass.
  • The composed tanstackRouter entries emit the same code as on main. Development builds of examples/react/quickstart-webpack-file-based (webpack) and e2e/react-router/rspack-basic-file-based (Rspack), with autoCodeSplitting on and off, are byte-identical to main's (Rspack: apart from the build timestamp and hash). With splitting on, both emit the webpack-style route HMR code.
  • e2e/react-start/hmr (route HMR on Vite, Vite bundled dev and Rsbuild) passes in CI.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Bug Fixes
    • Route hot reloading now uses the appropriate runtime for each bundler, resolving issues with Vite and preserving compatibility with Webpack and Rspack.
  • Configuration Changes
    • Removed the undocumented plugin.hmr.style setting. HMR style is selected automatically based on the bundler, so this option can no longer be used to override it.
    1. 🦋 Changeset detected

      Latest commit: 092d44fb787b47056747cb037e5dbaad225dd618

      The changes in this PR will be included in the next version bump.

      This PR includes changesets to release 7 packages
      NameType
      @tanstack/router-pluginPatch
      @tanstack/router-vite-pluginPatch
      @tanstack/start-plugin-corePatch
      @tanstack/react-start-rscPatch
      @tanstack/react-startPatch
      @tanstack/solid-startPatch
      @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. Review in Change Stack →
      Walkthrough

      The router plugin removes the plugin.hmr.style configuration option and the HmrOptions type. Bundler-specific plugin wiring now selects and passes the HMR style to HMR and code-splitter plugins.

      Changes: Router plugin HMR style selection

      Layer / File(s)Summary
      HMR style type and configuration
      .changeset/router-plugin-remove-hmr-style.md, packages/router-plugin/src/core/config.ts, packages/router-plugin/src/core/hmr/*, packages/router-plugin/src/core/code-splitter/plugins*, packages/router-plugin/src/index.ts
      The configuration schema and public exports drop HMR style configuration. The HMR module defines and exports HmrStyle, which its consumers now import from that module.
      Bundler style selection and propagation
      packages/router-plugin/src/core/router-code-splitter-plugin.ts, packages/router-plugin/src/core/router-composed-plugin.ts, packages/router-plugin/src/core/router-hmr-plugin.ts, packages/router-plugin/src/webpack.ts, packages/router-plugin/src/rspack.ts
      The composed plugin selects an HMR style from framework metadata and passes it to the HMR and code-splitter plugins. Webpack and Rspack entries pass webpack style directly and no longer rewrite plugin options.
      HMR style test helpers
      packages/router-plugin/tests/code-splitter-plugin-pipeline.test.ts, packages/router-plugin/tests/regression-helpers.ts
      The test helpers accept and forward an optional HMR style. The webpack HMR test selects webpack style through the helper.

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

      Change: Refactor · Severity of issue fixed: Low

      Sequence Diagram(s)

      sequenceDiagram
        participant unpluginRouterComposedFactory
        participant createRouterCodeSplitterPlugin
        participant createRouterHmrPlugin
        unpluginRouterComposedFactory->>createRouterCodeSplitterPlugin: Pass selected hmrStyle
        unpluginRouterComposedFactory->>createRouterHmrPlugin: Pass selected hmrStyle

      Possibly related PRs

      • TanStack/router#8804: This PR changes the same plugin factory signatures and wiring to pass framework metadata, which overlaps with this PR’s HMR style argument and selection.

      Suggested labels: package: router-plugin

      Suggested reviewers: schiller-manuel

      Merge Risk: Moderate · up to 092d4

      A patch upgrade may break builds that use the removed API. Confirm that this compatibility impact is acceptable before merging.

      Pre-merge checks: Passed 4 · Failed 1
      Failed Failed checks: 1 warning
      Check nameStatusExplanationResolution
      Docstring CoverageWarningDocstring coverage is 60.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documenta…Write docstrings for the functions missing them to satisfy the coverage threshold.
      Passed Passed checks: 4 passed
      Check nameStatusExplanation
      Title checkPassedThe title names the main change: removing the undocumented plugin.hmr.style option and the HmrOptions type from @tanstack/router-plugin. The raw summary confirms the config schema drops hmr, `…
      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.
      Description checkPassedThe description clearly explains the motivation, implementation changes, API impact, testing, release impact, and AI authorship. It does not include the template's exact Checklist and Release Impact h…
      Full details: Title check

      Explanation

      The title names the main change: removing the undocumented plugin.hmr.style option and the HmrOptions type from @tanstack/router-plugin. The raw summary confirms the config schema drops hmr, HmrOptions is no longer exported, and HMR style becomes an internal parameter. The refactor prefix is a reasonable label for this internal change. The title is specific and concise.

      Full details: Description check

      Explanation

      The description clearly explains the motivation, implementation changes, API impact, testing, release impact, and AI authorship. It does not include the template's exact Checklist and Release Impact headings or checkbox items, but it provides the required information in equivalent sections.

      Full details: Docstring Coverage

      Explanation

      Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%. 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 5 functions across 12 files. (1 skipped: 1 unsupported.)

      Resolution

      Write docstrings for the functions missing them to satisfy the coverage threshold.

      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.
    3. View your CI Pipeline Execution ↗ for commit 092d44fb787b47056747cb037e5dbaad225dd618

      CommandStatusDurationResult
      nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded11m 7sView ↗

      ☁️ Nx Cloud last updated this comment at 2026-11-03 17:14:55 UTC

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

    5. More templates

      @tanstack/arktype-adapter

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

      @tanstack/eslint-plugin-router

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

      @tanstack/eslint-plugin-start

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

      @tanstack/history

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

      @tanstack/react-router

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

      @tanstack/react-router-devtools

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

      @tanstack/react-router-ssr-query

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

      @tanstack/react-start

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

      @tanstack/react-start-client

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

      @tanstack/react-start-rsc

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

      @tanstack/react-start-server

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

      @tanstack/router-cli

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

      @tanstack/router-core

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

      @tanstack/router-devtools

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

      @tanstack/router-devtools-core

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

      @tanstack/router-generator

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

      @tanstack/router-plugin

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

      @tanstack/router-ssr-query-core

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

      @tanstack/router-utils

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

      @tanstack/router-vite-plugin

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

      @tanstack/solid-router

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

      @tanstack/solid-router-devtools

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

      @tanstack/solid-router-ssr-query

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

      @tanstack/solid-start

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

      @tanstack/solid-start-client

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

      @tanstack/solid-start-server

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

      @tanstack/start-client-core

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

      @tanstack/start-fn-stubs

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

      @tanstack/start-plugin-core

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

      @tanstack/start-server-core

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

      @tanstack/start-static-server-functions

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

      @tanstack/start-storage-context

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

      @tanstack/valibot-adapter

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

      @tanstack/virtual-file-routes

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

      @tanstack/vue-router

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

      @tanstack/vue-router-devtools

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

      @tanstack/vue-router-ssr-query

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

      @tanstack/vue-start

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

      @tanstack/vue-start-client

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

      @tanstack/vue-start-server

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

      @tanstack/zod-adapter

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

      commit: 092d44f

    6. Additional comments: 1
      .changeset/router-plugin-remove-hmr-style.md-2-2: 1

      2-2: Major · Data Integrity & Integration · Quick win

      **Unverified finding** Verification ran but could not confirm this finding. It is shown for review, not as a verified issue.

      Do not release these API removals as a patch.

      Existing TypeScript users can no longer import HmrOptions or pass plugin.hmr.style. A patch upgrade can therefore break their builds. (raw.githubusercontent.com)

      Retain the deprecated API until a major release, or release the removals as a major version.

      Review info
      Run configuration
      Commits

      Reviewing files that changed from the base of the PR and between 13b625683030ea4ab359495ecda570e05e472587 and 092d44fb787b47056747cb037e5dbaad225dd618.

      Files selected for processing: 15
      • .changeset/router-plugin-remove-hmr-style.md
      • packages/router-plugin/src/core/code-splitter/plugins.ts
      • packages/router-plugin/src/core/code-splitter/plugins/framework-plugins.ts
      • packages/router-plugin/src/core/code-splitter/plugins/react-stable-hmr-split-route-components.ts
      • packages/router-plugin/src/core/config.ts
      • packages/router-plugin/src/core/hmr/index.ts
      • packages/router-plugin/src/core/hmr/select-adapter.ts
      • packages/router-plugin/src/core/router-code-splitter-plugin.ts
      • packages/router-plugin/src/core/router-composed-plugin.ts
      • packages/router-plugin/src/core/router-hmr-plugin.ts
      • packages/router-plugin/src/index.ts
      • packages/router-plugin/src/rspack.ts
      • packages/router-plugin/src/webpack.ts
      • packages/router-plugin/tests/code-splitter-plugin-pipeline.test.ts
      • packages/router-plugin/tests/regression-helpers.ts
      Files with no reviewable changes: 2
      • packages/router-plugin/src/index.ts
      • packages/router-plugin/src/core/config.ts

      Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.

    7. 🚀 Changeset Version Preview

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

      🟨 Minor bumps

      PackageVersionReason
      @tanstack/router-plugin1.168.48 → 1.169.0Changeset

      🟩 Patch bumps

      PackageVersionReason
      @tanstack/react-start1.169.4 → 1.169.5Dependent
      @tanstack/react-start-rsc0.1.65 → 0.1.66Dependent
      @tanstack/router-vite-plugin1.167.48 → 1.167.49Dependent
      @tanstack/solid-start1.169.4 → 1.169.5Dependent
      @tanstack/start-plugin-core1.171.55 → 1.171.56Dependent
      @tanstack/vue-start1.169.4 → 1.169.5Dependent
    8. Bundle Size Benchmarks

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

    9. Merging this PR will degrade performance by 0.32%

      2 warnings, 1 note

      :warning: 53 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

      :warning: 1 benchmark with a significant change ran on different hardware

      Its base and head results were measured on machines with a different CPU, core count or memory, so the change might not come from the code. Run base and head on the same runner type.

      Learn more about Macro Runners

      See affected benchmarks

      :information_source: 20 benchmarks have no flamegraph

      The flamegraph wasn't generated: most of the time was spent in runtime internals, which would leave nothing useful to analyze.

      See affected benchmarks

      ⚡ 1 improved benchmark ❌ 1 (👁 1) regressed benchmark ✅ 192 untouched benchmarks ⏩ 3 skipped benchmarks1

      Performance Changes

      ModeBenchmarkBASEHEADEfficiency
      ⚡Memorymem client navigation-churn (solid)110.2 KB106.7 KB+3.35%
      👁Memorymem client loader-data-retention (react)111.1 KB115.6 KB-3.87%

      Tip

      Curious why performance improved? Comment @codspeedbot explain why performance improved on this PR, or directly use the CodSpeed MCP with your agent.


      Comparing router-plugin/remove-hmr-style (092d44f) with main (13b6256) 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.