refactor(router-plugin): remove `plugin.hmr.style` and `HmrOptions` #8856
main fromrefs/pull/8856/head·merged 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'emittedimport.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.hmris removed from the config schema, and theHmrOptionstype is no longer exported from@tanstack/router-plugin.- The HMR style is now an internal parameter.
createRouterCodeSplitterPluginandcreateRouterHmrPlugintake 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 composed plugin (
- The internal
HmrStyletype moves fromcore/config.tstocore/hmr. tanstackRouterfrom/webpackand/rspacknow passesunpluginRouterComposedFactoryto unplugin directly, so itsoptionsparameter has the Vite entry's type (Partial<Config | (() => Config)>) instead ofunknown. That type still accepts every value exceptnull.- Tests: the webpack route-HMR test in
code-splitter-plugin-pipeline.test.tsnow passes the style through the test helper instead ofplugin.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:eslintandtest:buildpass.@tanstack/start-plugin-core:test:unitandtest:typespass.- The composed
tanstackRouterentries emit the same code as on main. Development builds ofexamples/react/quickstart-webpack-file-based(webpack) ande2e/react-router/rspack-basic-file-based(Rspack), withautoCodeSplittingon 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.stylesetting. HMR style is selected automatically based on the bundler, so this option can no longer be used to override it.
- Removed the undocumented
- 1
Walkthrough
-
The router plugin removes the
plugin.hmr.styleconfiguration option and theHmrOptionstype. 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.tsThe 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.tsThe 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.tsThe 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 hmrStylePossibly 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-pluginSuggested reviewers:
schiller-manuel
Merge Risk:
Moderate · up to092d4-
A patch upgrade may break builds that use the removed API. Confirm that this compatibility impact is acceptable before merging.
Pre-merge checks:
4 · 1-
Failed checks: 1 warningCheck name Status Explanation Resolution Docstring Coverage 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. Documenta… Write docstrings for the functions missing them to satisfy the coverage threshold. Passed checks: 4 passed-
Check name Status Explanation Title check The title names the main change: removing the undocumented plugin.hmr.styleoption and theHmrOptionstype from@tanstack/router-plugin. The raw summary confirms the config schema dropshmr, `…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. Description check 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 h… Full details: Title check
-
Explanation
The title names the main change: removing the undocumented
plugin.hmr.styleoption and theHmrOptionstype from@tanstack/router-plugin. The raw summary confirms the config schema dropshmr,HmrOptionsis no longer exported, and HMR style becomes an internal parameter. Therefactorprefix 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.
CodeRabbit Verify#
- Run CodeRabbit Verify to test the changes in this pull request.
-
View your CI Pipeline Execution ↗ for commit 092d44fb787b47056747cb037e5dbaad225dd618
Command Status Duration Result nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded 11m 7s View ↗
☁️ Nx Cloud last updated this comment at
2026-11-03 17:14:55UTCgithub-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-plugin
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-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-router-vue-example-basic-jsx
- tanstack-router-vue-example-basic-file-based-jsx
- tanstack-router-vue-example-basic-file-based-sfc
@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@8856commit:
092d44f 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
HmrOptionsor passplugin.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-
- Source mode: Auto
- Repository: TanStack/router
- Branch: router-plugin/remove-hmr-style
- File: .coderabbit.yaml
- Commit: 092d44f
- Layers: Repository YAML
- Review profile: CHILL
- Plan: Advanced
- Run ID:
feb92eb7-ad44-42a8-b4fc-5942c834be83
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.mdpackages/router-plugin/src/core/code-splitter/plugins.tspackages/router-plugin/src/core/code-splitter/plugins/framework-plugins.tspackages/router-plugin/src/core/code-splitter/plugins/react-stable-hmr-split-route-components.tspackages/router-plugin/src/core/config.tspackages/router-plugin/src/core/hmr/index.tspackages/router-plugin/src/core/hmr/select-adapter.tspackages/router-plugin/src/core/router-code-splitter-plugin.tspackages/router-plugin/src/core/router-composed-plugin.tspackages/router-plugin/src/core/router-hmr-plugin.tspackages/router-plugin/src/index.tspackages/router-plugin/src/rspack.tspackages/router-plugin/src/webpack.tspackages/router-plugin/tests/code-splitter-plugin-pipeline.test.tspackages/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.
-
-
🚀 Changeset Version Preview#
1 package(s) bumped directly, 6 bumped as dependents.
🟨 Minor bumps#
Package Version Reason @tanstack/router-plugin1.168.48 → 1.169.0 Changeset 🟩 Patch bumps#
Package Version Reason @tanstack/react-start1.169.4 → 1.169.5 Dependent @tanstack/react-start-rsc0.1.65 → 0.1.66 Dependent @tanstack/router-vite-plugin1.167.48 → 1.167.49 Dependent @tanstack/solid-start1.169.4 → 1.169.5 Dependent @tanstack/start-plugin-core1.171.55 → 1.171.56 Dependent @tanstack/vue-start1.169.4 → 1.169.5 Dependent Bundle Size Benchmarks#
This pull request does not affect bundle size in any measured scenario.
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.
: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
: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.
⚡ 1improved benchmark❌ 1 (👁 1)regressed benchmark✅ 192untouched benchmarks⏩ 3skipped benchmarks1Performance Changes#
Mode Benchmark BASEHEADEfficiency ⚡ Memory mem client navigation-churn (solid)110.2 KB 106.7 KB +3.35% 👁 Memory mem client loader-data-retention (react)111.1 KB 115.6 KB -3.87% Tip
Curious why performance improved? Comment
@codspeedbot explain why performance improvedon this PR, or directly use the CodSpeed MCP with your agent.
Comparingrouter-plugin/remove-hmr-style(092d44f) withmain(13b6256)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. ↩
-
Sheraff(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
🦋 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
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