fix(router-plugin): generate routes and split code with esbuild #8628
main fromfix/router-plugin-esbuild·opened 🎯 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-basedandexamples/react/quickstart-esbuild-file-basedbuild with the esbuild CLI and never load the plugin;e2e/solid-router/basic-esbuild-file-basedskips all its tests;e2e/vue-router/basic-esbuild-file-basedpassed 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
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-plugin
View your CI Pipeline Execution ↗ for commit 68522389876c142ff00c4d9a364735600069c8c5
Command Status Duration Result nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded 9m View ↗ nx run-many --target=build --exclude=examples/*...✅ Succeeded 39s View ↗
☁️ Nx Cloud last updated this comment at
2026-10-07 16:54:12UTCImportant
Review skipped#
Review was skipped as selected files did not have any reviewable changes.
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis 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.yamlis excluded by!**/pnpm-lock.yaml
You can disable this status message by setting the
reviews.review_statustofalsein 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.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (7)
.changeset/esbuild-router-generation.mde2e/vue-router/basic-esbuild-file-based/src/routeTree.gen.tsexamples/solid/quickstart-esbuild-file-based/src/routeTree.gen.tspackages/router-plugin/package.jsonpackages/router-plugin/src/core/router-code-splitter-plugin.tspackages/router-plugin/src/core/router-generator-plugin.tspackages/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.mdThe 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.tsThe 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.tsNew 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 graphMerge Risk: ⚪ Minimal · up to
ce56eNo actionable merge-blocking issue remains in the reviewed changes. Merge after normal checks.
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)#
Check name Status Explanation Resolution Docstring Coverage ⚠️ Warning 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: … Write docstrings for the functions missing them to satisfy the coverage threshold. ✅ Passed checks (4 passed)
Check name Status Explanation Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request. Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request. Title check ✅ Passed The title clearly and concisely describes the esbuild route generation and code-splitting changes. Description check ✅ Passed The 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.
Comment `@coderabbitai help` to get the list of available commands.🚀 Changeset Version Preview#
6 package(s) bumped directly, 18 bumped as dependents.
🟩 Patch bumps#
Package Version Reason @tanstack/history1.162.4 → 1.162.5 Changeset @tanstack/react-router1.170.41 → 1.170.42 Changeset @tanstack/router-core1.171.34 → 1.171.35 Changeset @tanstack/router-plugin1.168.42 → 1.168.43 Changeset @tanstack/solid-router1.170.38 → 1.170.39 Changeset @tanstack/vue-router1.170.37 → 1.170.38 Changeset @tanstack/react-start1.168.60 → 1.168.61 Dependent @tanstack/react-start-client1.168.39 → 1.168.40 Dependent @tanstack/react-start-rsc0.1.59 → 0.1.60 Dependent @tanstack/react-start-server1.167.46 → 1.167.47 Dependent @tanstack/router-cli1.167.40 → 1.167.41 Dependent @tanstack/router-generator1.167.40 → 1.167.41 Dependent @tanstack/router-vite-plugin1.167.42 → 1.167.43 Dependent @tanstack/solid-start1.168.57 → 1.168.58 Dependent @tanstack/solid-start-client1.168.37 → 1.168.38 Dependent @tanstack/solid-start-server1.167.44 → 1.167.45 Dependent @tanstack/start-client-core1.170.34 → 1.170.35 Dependent @tanstack/start-plugin-core1.171.49 → 1.171.50 Dependent @tanstack/start-server-core1.169.39 → 1.169.40 Dependent @tanstack/start-static-server-functions1.167.39 → 1.167.40 Dependent @tanstack/start-storage-context1.167.36 → 1.167.37 Dependent @tanstack/vue-start1.168.56 → 1.168.57 Dependent @tanstack/vue-start-client1.167.40 → 1.167.41 Dependent @tanstack/vue-start-server1.167.44 → 1.167.45 Dependent 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:
Scenario Current (gzip) Initial (gzip) Raw Brotli Trend react-start.rsbuild.minimal100.4 KiB
+1 B100.2 KiB
0 B313.3 KiB
-1 B86.7 KiB
+11 B▂▂▁▁▁███████
react-start.rsbuild.minimal-iife100.8 KiB
-2 B100.6 KiB
-3 B314.3 KiB
-1 B87.0 KiB
-34 B▂▂▁▁▁███████
react-start.rsbuild.full103.6 KiB
-5 B103.5 KiB
-6 B323.4 KiB
-5 B89.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.
- Commit:
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@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@8628commit:
6852238Merging 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.
❌ 1regressed benchmark✅ 193untouched benchmarks⏩ 3skipped benchmarks1Warning
Please fix the performance issues or acknowledge them on CodSpeed.
Performance Changes#
Mode Benchmark BASEHEADEfficiency ❌ Memory mem server error-paths error (vue)112.3 KB 119.9 KB -6.37% Tip
Investigate this regression by commenting
@codspeedbot fix this regressionon this PR, or directly use the CodSpeed MCP with your agent.
Comparingfix/router-plugin-esbuild(6852238) withmain(5a641d8)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. ↩
-
Sign in to join this conversation.
🦋 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
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