Skip to content
Source
Sign inSign up
TanStack/router

fix(start-plugin-core): pass Start's router options through to the generator and code splitter #8861

MergedSheraff(GitHub profile, opens in a new tab)merged 4 commits intomain fromrefs/pull/8861/headmerged by Sheraff(GitHub profile, opens in a new tab)

Start's router options now reach the route generator and the code splitter the same way they reach a plain router app.

Fixes #7768 Fixes #8839

What's fixed

  • router.plugins reach the generator (#7768). Both Start hosts built plugins: [Start's own] after ...routerConfig, so your generator plugins never ran. A new shared startGeneratorConfig (src/start-router-plugin/generator-config.ts) builds the generator config for both Vite and Rsbuild. It appends your plugins after Start's own.

  • A function-form routeTreeFileFooter is called at every print. Start's Vite plugin cached its first result for the whole dev server. Rsbuild already called it at every print. Both now use the same function from startGeneratorConfig.

  • Rsbuild server builds keep codeSplittingOptions.deleteNodes. Start's Rsbuild plugin overwrote it with undefined on the server. It now passes your option through, as Vite already did. The client build still removes ssr, server and headers, as before.

  • The client route tree is matched by its exact module id (#8839). Start's Vite plugin matched it with new RegExp(<route tree path>) and didn't escape the path. Two failures came from that:

    • A + or another regex character in the project path meant the pattern never matched. The client got the full route tree, so server-only routes weren't pruned and server code shipped to the client.
    • The . matched any character, so a file named src/routeTree-gen.ts was replaced by the client route tree.

    The filter is now ^<escaped path>(?:\?.*)?$, and the handler checks the id as well.

The code comes from #8817 (generator-config.ts and the Vite matcher), so #8817's diff shrinks when main is merged into it. One difference: clientRouteTree is optional here, because Start's Rsbuild plugin on main has no client route tree plugin yet (that's #8545).

Tests

packages/start-plugin-core/tests/integration/start-router-wiring.test.ts builds and serves real Start apps in temporary directories. It uses the built @tanstack/react-start plugin/vite and plugin/rsbuild entries, as an installed app would (helper: tests/integration/start-app.ts). Every test failed on main before the fix, except the Vite deleteNodes row, which is a control:

testViteRsbuild
generator plugins of router.plugins see the route treefails on mainfails on main
deleteNodes: the server build erases the option, the client build keeps itpasses on main (control)fails on main
app path my app (2)+: the client route tree leaves out the server-only routefails on main— (no client route tree yet, #8545)
a file named routeTree-gen.ts keeps its own codefails on main (MISSING_EXPORT)—
dev: a function-form routeTreeFileFooter gives its current lines at every printfails on main— (already correct on main)

The tests run in a new test:integration target (Vitest project integration). It depends on building start-plugin-core itself and @tanstack/react-start (nx.targets in package.json). Vitest loads both packages' dist natively (server.deps.external), so the plugin and the loaders Rspack loads share one module instance.

test:unit (Vitest project unit) is unchanged from main, dependencies included. The root test:pr and test:ci scripts list test:integration, so the Linux Test job runs it. The cross-platform job (compiler-platforms.yml) runs only test:unit, so it doesn't. Before the move, the Vite dev footer test timed out there on Linux arm64 and Windows. The cause was a race: the generator prints the first route tree before Vite creates its watcher, and a route file written during the watcher's initial scan is never reported. The test now waits for the watcher first: it writes an ignored -watch-probe.ts until the watcher reports it (watcherReady), and only then adds the route.

Validation

Run locally with Node 26.12.1, a frozen install, Nx, and at most 2 test workers:

  • pnpm format: done.
  • @tanstack/start-plugin-core: test:unit (49 files, 872 passed + 1 expected fail, no type errors, as on main), test:integration (7 passed; 5/5 runs through Nx after the watcher fix, plus the dev test 5/5 pinned to one CPU core), test:types, test:eslint, test:build. All pass.
  • Consumers: test:unit of @tanstack/solid-start, @tanstack/vue-start and @tanstack/react-start-client passes.
  • e2e: tanstack-react-start-e2e-basic:test:e2e passes in every mode (Vite ssr, spa, prerender, preview; Rsbuild ssr, ssr-iife, spa, prerender, preview). tanstack-react-start-e2e-server-routes:test:e2e passes.
  • Bundle size: every Start scenario (React, Solid and Vue, Vite and Rsbuild; 12 metrics) is byte-identical to main, hashed file names included. Only build-time plugin code changes, so the bundle-size pass doesn't apply.

Merging into #8817

Test-merged locally: this branch, then #8817's head (5bc674ea80) on top. Six files conflict on top of what main alone already conflicts with:

fileconflictresolution
src/start-router-plugin/generator-config.tsadd/add (doc line, clientRouteTree? optional, conditional spread)take #8817's side (clientRouteTree required)
src/vite/start-router-plugin/plugin.tscontenttake #8817's side (it already has the exact-id matcher and startGeneratorConfig)
src/rsbuild/start-router-plugin.tsmodify/deletedelete it, as #8817 does (rsbuild/router-generator.ts and the planners replace it)
vite.config.tscontent (the unit and integration projects)take #8817's side
package.json (start-plugin-core)content (test, test:unit, test:integration scripts)take #8817's side
package.json (root)content (test:pr and test:ci: both sides add test:integration; #8817 also adds test:noncompiler)take #8817's side

Watch out in start-plugin-core's package.json: besides the scripts conflict, git merges cleanly into two top-level "nx" keys (this PR's, then #8817's). Take #8817's whole file, not just its side of the conflict block.

Also after the merge:

  • delete tests/integration/start-app.ts and tests/integration/start-router-wiring.test.ts. #8817's own tests cover the same scenarios (start-build-options, start-dev-route-tree-footer, start-compose-project-path), and the probe plugin here uses main's onRouteTreeChanged({ routeNodes }) hook, which #8817 replaces with { model };
  • .changeset/start-compiler-yuku.md: drop the Rsbuild bullet "router.codeSplittingOptions.deleteNodes applies to the server environment…". Cut the "Other" bullet down to the footer following quoteStyle and semicolons;
  • PR description: drop the "Start router options follow one rule on Vite and Rsbuild…" bullet (client addHmr was already on, on both bundlers), and "Closes #7768" and "Closes #8839".

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Bug Fixes
    • Router plugins now run alongside framework plugins, and function-based route-tree footer updates are reflected when routes change.
    • Server builds retain configured code-splitting options. Vite more reliably selects the intended client route tree, including when paths contain special characters or similarly named files exist.
  • Tests
    • Added integration coverage for router configuration across Vite and Rsbuild, including route-tree updates and code-splitting behavior. Integration tests are now included in pull request and CI test runs.
    1. 🦋 Changeset detected

      Latest commit: e3c74a38e9dcec830d136f3ef88e85d9142c8e36

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

      This PR includes changesets to release 5 packages
      NameType
      @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. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: start-plugin-core

    3. Review in Change Stack →

      No actionable comments were generated in the recent review.

      Walkthrough

      Start now builds router generator configuration through a shared function used by Vite and Rsbuild. The changes update Vite route-tree matching and Rsbuild server code-splitting options. They also add integration tests for these behaviors.

      Changes: Start router wiring

      Layer / File(s)Summary
      Shared generator configuration and bundler wiring
      packages/start-plugin-core/src/start-router-plugin/generator-config.ts, packages/start-plugin-core/src/rsbuild/start-router-plugin.ts, packages/start-plugin-core/src/vite/start-router-plugin/plugin.ts, .changeset/start-router-plugin-wiring.md
      A shared function assembles router options, the route-tree footer, and generator plugins, including app-defined plugins. Vite and Rsbuild use this configuration. Rsbuild passes configured deleteNodes options for server builds. Vite matches the client route tree using an escaped path and normalized module ID.
      Integration test setup and app harness
      package.json, packages/start-plugin-core/package.json, packages/start-plugin-core/vite.config.ts, packages/start-plugin-core/tests/integration/start-app.ts
      Test scripts and Nx configuration include integration tests. Vitest separates unit and integration projects. Helpers create temporary apps and run builds or a Vite dev server.
      Router wiring integration tests
      packages/start-plugin-core/tests/integration/start-router-wiring.test.ts
      Vite and Rsbuild tests check app generator plugins and code-splitting options. Vite tests also check route-tree matching and updated function-form footers.

      Estimated code review effort: 3 (Moderate) | ~25 minutes

      Change: Bug fix · Severity of issue fixed: Medium

      Possibly related issues

      • TanStack/router#8839: The PR changes Vite route-tree matching to use an escaped path and exact normalized module ID. Its integration tests cover paths with regex characters.

      Possibly related PRs

      • TanStack/router#8291: Both PRs change server code-splitting behavior. This PR passes router.codeSplittingOptions.deleteNodes into the Rsbuild server build.
      Merge Risk: Minimal · up to e3c74

      No merge-blocking issue was established in the router wiring or integration setup.

      Pre-merge checks: Passed 5
      Check nameStatusExplanation
      Title checkPassedThe title clearly and concisely identifies the main change: passing Start router options to the generator and code splitter.
      Description checkPassedThe description is detailed, relevant, and covers the changes, motivation, testing, known scope limits, and AI assistance. It does not reproduce the template's checklist and release-impact sections, b…
      Linked Issues checkPassed[#7768] startGeneratorConfig in src/start-router-plugin/generator-config.ts builds the generator plugin list as: client route tree (Vite only), routes manifest, prerender (when enabled), then `...…
      Out of Scope Changes checkPassedThe production changes address the linked issues and the PR title. They cover the shared generator config (generator-config.ts), the Vite client route-tree matcher and handler (plugin.ts), and the…
      Docstring CoveragePassedDocstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
      Full details: Description check

      Explanation

      The description is detailed, relevant, and covers the changes, motivation, testing, known scope limits, and AI assistance. It does not reproduce the template's checklist and release-impact sections, but it is mostly complete and provides the key required information.

      Full details: Linked Issues check

      Explanation

      [#7768] startGeneratorConfig in src/start-router-plugin/generator-config.ts builds the generator plugin list as: client route tree (Vite only), routes manifest, prerender (when enabled), then ...(router.plugins ?? []). User plugins are no longer overwritten. The Vite plugin (src/vite/start-router-plugin/plugin.ts) and the Rsbuild plugin both call this function. The routeTreeFileFooter is a function that is called at every print, so the cached footer is removed. [#8839] The Vite client route-tree load filter now uses ^${escapeRegExp(path)}(?:\?.*)?$, which matches the exact module ID with an optional query. The handler strips the query, normalizes the ID, and returns null unless it equals the resolved route tree path. This fixes the unescaped + case and the . wildcard case (routeTree-gen.ts). The integration tests described in the PR cover generator-plugin hooks on both bundlers, the regex-character path, and the similarly named file. The other new RegExp sites mentioned in #8839 (for example rsbuild/watch-ignored.js) are not changed. The issue treats them as suggestions, and the root cause of the reported leak is fixed. The memory growth in #8839 is a symptom of that leak. The PR does not claim to change those sites.

      Full details: Out of Scope Changes check

      Explanation

      The production changes address the linked issues and the PR title. They cover the shared generator config (generator-config.ts), the Vite client route-tree matcher and handler (plugin.ts), and the Rsbuild generator config and deleteNodes forwarding (rsbuild/start-router-plugin.ts). The deleteNodes change is a router-option pass-through, which the PR title ("pass Start's router options through to the generator and code splitter") covers. The integration-test helpers and test, the Vitest project split, the Nx test:integration target, the root script updates, and the changeset support verification and the new test target. No unrelated production behavior or unrelated project area appears in the reviewed summary. The incremental changes since the previous reviewed head (4bf6bcc) were not individually re-read in this assessment. The whole-PR diff of the Vite plugin and the shared config was checked at the reviewed head, and it matches the described scope.

      Full details: Docstring Coverage

      Explanation

      Docstring coverage is 100.00% which is sufficient. 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 7 functions across 6 files.

      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 4bf6bcc653d0ce419bc9ccd5328a127ceb8e3e35 and e3c74a38e9dcec830d136f3ef88e85d9142c8e36.

      Files selected for processing: 2
      • packages/start-plugin-core/tests/integration/start-app.ts
      • packages/start-plugin-core/tests/integration/start-router-wiring.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. View your CI Pipeline Execution ↗ for commit e3c74a38e9dcec830d136f3ef88e85d9142c8e36

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

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

    5. 🚀 Changeset Version Preview

      5 package(s) bumped directly, 5 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/start-plugin-core1.171.55 → 1.171.56Changeset
      @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/vue-start1.169.4 → 1.169.5Dependent
    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@8861

      @tanstack/eslint-plugin-router

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

      @tanstack/eslint-plugin-start

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

      @tanstack/history

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

      @tanstack/react-router

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

      @tanstack/react-router-devtools

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

      @tanstack/react-router-ssr-query

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

      @tanstack/react-start

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

      @tanstack/react-start-client

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

      @tanstack/react-start-rsc

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

      @tanstack/react-start-server

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

      @tanstack/router-cli

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

      @tanstack/router-core

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

      @tanstack/router-devtools

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

      @tanstack/router-devtools-core

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

      @tanstack/router-generator

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

      @tanstack/router-plugin

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

      @tanstack/router-ssr-query-core

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

      @tanstack/router-utils

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

      @tanstack/router-vite-plugin

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

      @tanstack/solid-router

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

      @tanstack/solid-router-devtools

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

      @tanstack/solid-router-ssr-query

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

      @tanstack/solid-start

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

      @tanstack/solid-start-client

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

      @tanstack/solid-start-server

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

      @tanstack/start-client-core

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

      @tanstack/start-fn-stubs

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

      @tanstack/start-plugin-core

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

      @tanstack/start-server-core

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

      @tanstack/start-static-server-functions

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

      @tanstack/start-storage-context

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

      @tanstack/valibot-adapter

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

      @tanstack/virtual-file-routes

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

      @tanstack/vue-router

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

      @tanstack/vue-router-devtools

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

      @tanstack/vue-router-ssr-query

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

      @tanstack/vue-start

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

      @tanstack/vue-start-client

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

      @tanstack/vue-start-server

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

      @tanstack/zod-adapter

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

      commit: e3c74a3

    8. Merging this PR will improve performance by 1.24%

      2 warnings, 1 note

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

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

      Performance Changes

      ModeBenchmarkBASEHEADEfficiency
      ⚡Memorymem client unique-location-churn (react)80 KB76.2 KB+4.99%
      ⚡Memorymem client unique-location-churn (vue)83.3 KB80.7 KB+3.17%
      👁Memorymem client interrupted-navigations (vue)93.7 KB97.8 KB-4.2%

      Tip

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


      Comparing start-plugin-core/router-plugin-wiring (e3c74a3) 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. ↩

      • Fix comments: Fix CodeRabbit comments on this PR
      Resolvedby coderabbitai[bot](GitHub profile, opens in a new tab)
    9. Sheraff(GitHub profile, opens in a new tab)replied on packages/start-plugin-core/tests/integration/start-router-wiring.test.ts lines 138 to 141

      Fixed in e3c74a38e9. The generator prints the first route tree in configResolved, before Vite creates its watcher, so waiting for the first tree did not prove the watcher was ready. The test now writes src/routes/-watch-probe.ts (ignored by the generator, - prefix) until server.watcher reports an event for it, then writes later.tsx once (watcherReady in tests/integration/start-app.ts). test:integration passed 5/5 runs through Nx, and the dev test passed 5/5 more pinned to one CPU core.

    10. coderabbitai[bot](GitHub profile, opens in a new tab)replied on packages/start-plugin-core/tests/integration/start-router-wiring.test.ts lines 138 to 141
      Analysis chain

      Script executed:

      #!/bin/bash
      for file in AGENTS.md packages/AGENTS.md packages/start-plugin-core/AGENTS.md; do
        if test -f "$file"; then printf '\n--- %s ---\n' "$file"; cat "$file"; fi
      done
      fd AGENTS.md packages/start-plugin-core/tests
      ast-grep outline packages/start-plugin-core/tests/integration/start-app.ts --items all
      ast-grep outline packages/start-plugin-core/tests/integration/start-router-wiring.test.ts --items all
      printf '\n--- watcher helper ---\n'
      rg -n -C25 'export async function watcherReady|export async function until' packages/start-plugin-core/tests/integration/start-app.ts
      printf '\n--- dev test ---\n'
      sed -n '120,180p' packages/start-plugin-core/tests/integration/start-router-wiring.test.ts

      Length of output: 14615


      @Sheraff Verified the fix in the current code. The test awaits watcherReady before writing later.tsx once. The helper waits for a watcher event on the ignored probe and removes its listener afterward. The test then checks both /later and the updated footer.

      This addresses the watcher-startup race. I did not rerun tests; your repeated passing runs provide the runtime validation.


      Learnings added
      Learnt from: Sheraff
      Repo: TanStack/router PR: 8861
      File: packages/start-plugin-core/tests/integration/start-router-wiring.test.ts:138-141
      Timestamp: 2026-11-03T19:38:06.222Z
      Learning: Within repository "TanStack/router", only for files matching one of ["packages/start-plugin-core/tests/integration/start-router-wiring.test.ts"]: When reviewing watcher-driven route-add tests in packages/start-plugin-core/tests/integration/start-router-wiring.test.ts, require watcher readiness before writing the new route. Do not treat the first generated route tree as proof of readiness: generation occurs in configResolved before Vite creates its watcher. Use watcherReady or equivalent observed watcher activity before the route write, then verify the regenerated tree.

      Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.


      If you found this review helpful, would you consider giving us a shout-out on X?

      Thank you for using CodeRabbit!

      Review thread resolved.

      You are interacting with an AI system.

Sign in to join this conversation.