Skip to content
Source
Sign inSign up
TanStack/router

fix(router-plugin): generate routes and split code with esbuild #8628

OpenSheraff(GitHub profile, opens in a new tab)wants to merge 3 commits intomain fromfix/router-plugin-esbuildopened

🎯 Changes

Found while validating #8504 (the Yuku compiler migration), but independent of it: this PR targets main and doesn't touch Babel or Yuku.

esbuild code splitting never worked. The esbuild integration of @tanstack/router-plugin only initialized the route generator and never ran it, so routesByFile stayed empty and no route was ever split. The code splitter also had no esbuild hook, so with the generator fixed alone builds crashed on codeSplittingOptions. Nothing caught it because no test exercised the plugin through esbuild:

  • e2e/react-router/basic-esbuild-file-based and examples/react/quickstart-esbuild-file-based build with the esbuild CLI and never load the plugin;
  • e2e/solid-router/basic-esbuild-file-based skips all its tests;
  • e2e/vue-router/basic-esbuild-file-based passed without any route being split.

The fix runs the generator from esbuild's onStart and sets up the code splitter's config from the esbuild config hook. The two route trees built through the plugin are regenerated (they were still in an old generator format).

Bundler integration tests. packages/router-plugin/tests/bundler-integrations.test.ts runs webpack, Rspack and esbuild programmatically on a small app, in production and development, and asserts that the route tree is generated, that the entry keeps the loader but not the component, that exactly one other chunk contains the component, and that the output runs in Node (loader result and the lazily loaded, rendered component). For webpack and Rspack it also runs a watch build, edits the route's loader and applies the hot update, asserting the live route gets the new loader while route and component identity are kept (removing hot.accept() from the webpack HMR adapter makes it fail). It runs in about 2 s as part of @tanstack/router-plugin:test:unit. Before this, webpack had no tests at all and Rspack only had production e2e.

The esbuild tests fail without the fix (Could not resolve "./routeTree.gen.js"). esbuild is added as a router-plugin devDependency, at the same ^0.27.4 used elsewhere in the repo.

Validation: @tanstack/router-plugin test:unit, test:types, test:eslint and test:build pass; the esbuild example and e2e builds pass; test:e2e passes for the vue (22 tests) and react (5 tests) esbuild e2e apps.

✅ Checklist

  • I have followed the steps in the Contributing guide.
  • I have tested code changes locally with the relevant test commands, or tests do not apply to this pull request.
  • I fully understand the code in this pull request, including any code generated with AI assistance.

🚀 Release Impact

  • This change affects published code, and I have generated a changeset.
  • This change is docs/CI/dev-only (no release).

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features
    • The esbuild integration now generates the route tree before bundling, enabling automatic code splitting for file-based routes.
  • Bug Fixes
    • Routes are no longer left in the main bundle when automatic code splitting is enabled with esbuild.
  • Tests
    • Added integration coverage for route generation, lazy-loaded components, loader output, runtime rendering, and development updates across supported bundlers.
    1. 🦋 Changeset detected

      Latest commit: 68522389876c142ff00c4d9a364735600069c8c5

      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. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-plugin

    3. View your CI Pipeline Execution ↗ for commit 68522389876c142ff00c4d9a364735600069c8c5

      CommandStatusDurationResult
      nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded9mView ↗
      nx run-many --target=build --exclude=examples/*...✅ Succeeded39sView ↗

      ☁️ Nx Cloud last updated this comment at 2026-10-07 16:54:12 UTC

    4. Review in Change Stack →

      Important

      Review skipped

      Review was skipped as selected files did not have any reviewable changes.

      ⛔ Files ignored due to path filters (1)
      • pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
      ⚙️ Run configuration
      • Configuration used: Repository: TanStack/router/.coderabbit.yaml
      • Review profile: CHILL
      • Plan: Advanced
      • Run ID: 4f920033-465c-408d-a636-4f800ec2adbe
      📥 Commits

      Reviewing files that changed from the base of the PR and between ce56e9f48971d3fade57a84db0f9e194a7659256 and 68522389876c142ff00c4d9a364735600069c8c5.

      ⛔ Files ignored due to path filters (1)
      • pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

      You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

      Use the checkbox below for a quick retry:

      • 🔍 Trigger review

      No actionable comments were generated in the recent review. 🎉

      ℹ️ Recent review info
      ⚙️ Run configuration
      • Configuration used: Repository: TanStack/router/.coderabbit.yaml
      • Review profile: CHILL
      • Plan: Advanced
      • Run ID: b97d7992-20d8-441e-b9e9-284082e1162e
      📥 Commits

      Reviewing files that changed from the base of the PR and between 30fc108a5ebbc4eadd48439282bf1c27d55fbb94 and ce56e9f48971d3fade57a84db0f9e194a7659256.

      ⛔ Files ignored due to path filters (1)
      • pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
      📒 Files selected for processing (7)
      • .changeset/esbuild-router-generation.md
      • e2e/vue-router/basic-esbuild-file-based/src/routeTree.gen.ts
      • examples/solid/quickstart-esbuild-file-based/src/routeTree.gen.ts
      • packages/router-plugin/package.json
      • packages/router-plugin/src/core/router-code-splitter-plugin.ts
      • packages/router-plugin/src/core/router-generator-plugin.ts
      • packages/router-plugin/tests/bundler-integrations.test.ts

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


      📝 Walkthrough

      Walkthrough

      The router plugin now initializes configuration for esbuild and generates routes before esbuild resolves the entry graph. Generated route outputs are updated, and integration tests cover route generation, code splitting, runtime rendering, and development HMR across bundlers.

      Changes

      Esbuild router generation

      Layer / File(s)Summary
      Esbuild plugin integration
      packages/router-plugin/package.json, packages/router-plugin/src/core/router-code-splitter-plugin.ts, packages/router-plugin/src/core/router-generator-plugin.ts, .changeset/esbuild-router-generation.md
      The plugin adds an esbuild configuration hook and registers route generation with build.onStart(). The package adds esbuild as a development dependency. A patch changeset describes the esbuild behavior.
      Generated route outputs
      examples/solid/quickstart-esbuild-file-based/src/routeTree.gen.ts, e2e/vue-router/basic-esbuild-file-based/src/routeTree.gen.ts
      The Solid generated route tree uses renamed imports and explicit route IDs and paths. The Vue generated route tree reorders entries while retaining route metadata and relationships.
      Bundler integration and HMR tests
      packages/router-plugin/tests/bundler-integrations.test.ts
      New integration tests check route generation, split component chunks, and runtime rendering in webpack, Rspack, and esbuild builds. Webpack and Rspack development tests also check route HMR updates.

      Priority: ➖ Normal

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

      Change: Bug fix

      Sequence Diagram(s)

      sequenceDiagram
        participant Esbuild
        participant RouterGeneratorPlugin
        participant Generate
        Esbuild->>RouterGeneratorPlugin: Call setup(build)
        RouterGeneratorPlugin->>Esbuild: Register build.onStart()
        Esbuild->>Generate: Generate routes before resolving the entry graph

      Merge Risk: ⚪ Minimal · up to ce56e

      No actionable merge-blocking issue remains in the reviewed changes. Merge after normal checks.

      🚥 Pre-merge checks | ✅ 4 | ❌ 1

      ❌ Failed checks (1 warning)

      Check nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring coverage is 15.38% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 13 functions across 5 files. (2 skipped: …Write docstrings for the functions missing them to satisfy the coverage threshold.
      ✅ Passed checks (4 passed)
      Check nameStatusExplanation
      Linked Issues check✅ PassedCheck skipped because no linked issues were found for this pull request.
      Out of Scope Changes check✅ PassedCheck skipped because no linked issues were found for this pull request.
      Title check✅ PassedThe title clearly and concisely describes the esbuild route generation and code-splitting changes.
      Description check✅ PassedThe description explains the problem, fix, tests, validation results, and release impact. It includes all required template sections and checklist items.
      Full details: Docstring Coverage

      Explanation

      Docstring coverage is 15.38% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 13 functions across 5 files. (2 skipped: 2 unsupported.)

      ✨ Finishing Touches 💡 1
      📝 Generate docstrings 💡
      • Commit to this branch
      • Create a new PR
      🧪 Generate unit tests (beta)
      • Commit to this branch
      • Create a new PR
      • Autopilot · 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
      Comment `@coderabbitai help` to get the list of available commands.
    5. 🚀 Changeset Version Preview

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

      🟩 Patch bumps

      PackageVersionReason
      @tanstack/history1.162.4 → 1.162.5Changeset
      @tanstack/react-router1.170.41 → 1.170.42Changeset
      @tanstack/router-core1.171.34 → 1.171.35Changeset
      @tanstack/router-plugin1.168.42 → 1.168.43Changeset
      @tanstack/solid-router1.170.38 → 1.170.39Changeset
      @tanstack/vue-router1.170.37 → 1.170.38Changeset
      @tanstack/react-start1.168.60 → 1.168.61Dependent
      @tanstack/react-start-client1.168.39 → 1.168.40Dependent
      @tanstack/react-start-rsc0.1.59 → 0.1.60Dependent
      @tanstack/react-start-server1.167.46 → 1.167.47Dependent
      @tanstack/router-cli1.167.40 → 1.167.41Dependent
      @tanstack/router-generator1.167.40 → 1.167.41Dependent
      @tanstack/router-vite-plugin1.167.42 → 1.167.43Dependent
      @tanstack/solid-start1.168.57 → 1.168.58Dependent
      @tanstack/solid-start-client1.168.37 → 1.168.38Dependent
      @tanstack/solid-start-server1.167.44 → 1.167.45Dependent
      @tanstack/start-client-core1.170.34 → 1.170.35Dependent
      @tanstack/start-plugin-core1.171.49 → 1.171.50Dependent
      @tanstack/start-server-core1.169.39 → 1.169.40Dependent
      @tanstack/start-static-server-functions1.167.39 → 1.167.40Dependent
      @tanstack/start-storage-context1.167.36 → 1.167.37Dependent
      @tanstack/vue-start1.168.56 → 1.168.57Dependent
      @tanstack/vue-start-client1.167.40 → 1.167.41Dependent
      @tanstack/vue-start-server1.167.44 → 1.167.45Dependent
    6. Bundle Size Benchmarks

      • Commit: 3cb1c4817605
      • Measured at: 2026-10-07T16:46:08.804Z
      • Baseline source: history:5a641d859c92
      • Dashboard: bundle-size history

      The following scenarios have bundle-size changes compared with the baseline:

      ScenarioCurrent (gzip)Initial (gzip)RawBrotliTrend
      react-start.rsbuild.minimal100.4 KiB
      +1 B
      100.2 KiB
      0 B
      313.3 KiB
      -1 B
      86.7 KiB
      +11 B
      ▂▂▁▁▁███████
      react-start.rsbuild.minimal-iife100.8 KiB
      -2 B
      100.6 KiB
      -3 B
      314.3 KiB
      -1 B
      87.0 KiB
      -34 B
      ▂▂▁▁▁███████
      react-start.rsbuild.full103.6 KiB
      -5 B
      103.5 KiB
      -6 B
      323.4 KiB
      -5 B
      89.5 KiB
      +86 B
      ▂▂▁▁▁██████▇

      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.

    7. More templates

      @tanstack/arktype-adapter

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

      @tanstack/eslint-plugin-router

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

      @tanstack/eslint-plugin-start

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

      @tanstack/history

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

      @tanstack/nitro-v2-vite-plugin

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

      @tanstack/react-router

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

      @tanstack/react-router-devtools

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

      @tanstack/react-router-ssr-query

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

      @tanstack/react-start

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

      @tanstack/react-start-client

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

      @tanstack/react-start-rsc

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

      @tanstack/react-start-server

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

      @tanstack/router-cli

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

      @tanstack/router-core

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

      @tanstack/router-devtools

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

      @tanstack/router-devtools-core

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

      @tanstack/router-generator

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

      @tanstack/router-plugin

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

      @tanstack/router-ssr-query-core

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

      @tanstack/router-utils

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

      @tanstack/router-vite-plugin

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

      @tanstack/solid-router

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

      @tanstack/solid-router-devtools

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

      @tanstack/solid-router-ssr-query

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

      @tanstack/solid-start

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

      @tanstack/solid-start-client

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

      @tanstack/solid-start-server

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

      @tanstack/start-client-core

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

      @tanstack/start-fn-stubs

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

      @tanstack/start-plugin-core

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

      @tanstack/start-server-core

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

      @tanstack/start-static-server-functions

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

      @tanstack/start-storage-context

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

      @tanstack/valibot-adapter

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

      @tanstack/virtual-file-routes

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

      @tanstack/vue-router

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

      @tanstack/vue-router-devtools

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

      @tanstack/vue-router-ssr-query

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

      @tanstack/vue-start

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

      @tanstack/vue-start-client

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

      @tanstack/vue-start-server

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

      @tanstack/zod-adapter

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

      commit: 6852238

    8. Merging this PR will degrade performance by 6.37%

      :warning: Different runtime environments detected

      Some benchmarks with significant performance changes were compared across different runtime environments, which may affect the accuracy of the results.

      Open the report in CodSpeed to investigate

      ❌ 1 regressed benchmark ✅ 193 untouched benchmarks ⏩ 3 skipped benchmarks1

      Warning

      Please fix the performance issues or acknowledge them on CodSpeed.

      Performance Changes

      ModeBenchmarkBASEHEADEfficiency
      ❌Memorymem server error-paths error (vue)112.3 KB119.9 KB-6.37%

      Tip

      Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.


      Comparing fix/router-plugin-esbuild (6852238) with main (5a641d8) 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.