Skip to content
Source
Sign inSign up
TanStack/router

perf(router-plugin): parse reference routes once #8454

OpenSheraff(GitHub profile, opens in a new tab)wants to merge 3 commits intomain fromperf/router-reference-parse-onceopened

Summary

  • Parse reference-route source once for grouping detection, shared-binding analysis and reference compilation.
  • Complete both analyses before compiler mutation and keep the AST local to one transform; no persistent cache or new invalidation state.
  • Use AST-taking helpers directly for grouping and shared-binding analysis. Keep the source-taking reference compiler for the HMR-only plugin, which still uses it.
  • Add exact code/map parity coverage, shared-destructuring fixtures, scope-aware compiler-hook tests, root-route/HMR parity, reference/virtual/shared freshness, and Start client-deletion coverage.
  • Include a router-plugin patch changeset. Keep measurement benchmarks out of the committed PR; the build measurements below remain the original results.

Full-app build performance

Complete React Start client and SSR builds using createBuilder().buildApp(). Exact baseline and candidate package builds, identical app sources/paths and other dependencies, discarded warmups, four measured samples per implementation in balanced ABBAABBA order.

WorkloadBefore (median)After (median)Elapsed reduction
100 leaf routes2.552 s2.376 s6.9%
1,000 leaf routes16.261 s14.714 s9.5%
100 leaves / 200 server functions3.014 s2.848 s5.5%
1,000 leaves / 2,000 server functions22.295 s20.361 s8.7%

Client code, SSR code, filenames and generated route trees matched exactly across all samples. Focused tiny-route benchmarks also improved mean time by approximately 8–24%, depending on workload. Memory results were variable; no stable memory reduction is claimed.

Measured on Linux / AMD Ryzen 7 255, Node 24.8.0, pnpm 11.21.0 and Vite 8.0.14. Generated flat-route workloads model clean builds on a warm filesystem; results are not claims about every application or incremental HMR.

Original validation

  • Router-plugin: 786 unit tests, TypeScript 5.6–7.0, ESLint and publint/attw passed.
  • Public-plugin behavioral comparisons passed against both baseline and candidate; code and sourcemap parity is asserted before focused timings.
  • Start-plugin-core: 540 unit tests, types and ESLint passed.
  • Production Router browser tests passed: React 6, Solid 5, Vue JSX 22, Vue SFC 22.
  • Focused production Start SSR browser tests passed: React 61, Solid 54.
  • Final uncached bundle matrix rebuilt all 26 package dependencies: zero deltas across all 18 scenarios. All 57 emitted JS/MJS/CJS files (5,345,770 bytes) matched byte-for-byte.
  • Formatting and git diff --check passed.

Review follow-up

  • Removed the committed reference-pipeline benchmark as requested.
  • Removed the unused source-taking grouping/shared-binding wrappers. Tests now call the AST helpers directly; the source-taking reference compiler remains because the HMR-only plugin uses it.
  • Added single-parse coverage for shared destructured bindings and filename-dependent TypeScript parsing. Updated the architecture notes.
  • Router-plugin: 788 unit tests; Start-plugin-core: 540 unit tests. Both packages passed TypeScript 5.6–7.0, ESLint, publint and attw.
  • Production Router browser tests: React 6, Solid 120, Vue JSX 22, Vue SFC 22. Focused built React Start Vite SSR tests: 17.
  • Cleanup versus original PR head: all 18 bundle scenarios have zero size deltas; all 57 emitted JS/MJS/CJS files matched byte-for-byte. Final package rebuild was uncached.
  • The full-app timing table above remains the original Linux measurement. Temporary focused measurements reconfirmed the single-parse benefit; no additional speedup is claimed for this cleanup.

The compiler-helper extraction and plugin wiring form one optimization; no unrelated compiler behavior change is included. Measurement-script compression is a separate PR.

Summary by CodeRabbit

  • Performance
    • Route code-splitting builds now parse each reference route once for grouping detection, shared-binding analysis, and compilation.
  • Compatibility
    • Existing route code-splitting behavior and generated output are preserved.
    1. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-plugin

    2. Review in Change Stack →

      Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

      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: ab3633ec-2d51-4f01-991b-92d34a4d39cf

      📥 Commits

      Reviewing files that changed from the base of the PR and between 528fb72962e2cadfe72d5e4b2c6322e3480200c5 and 52c37b505d3d23b1274e4d4488cf84243869b9d7.

      📒 Files selected for processing (37)
      • .changeset/quick-dingos-decide.md
      • packages/router-plugin/ARCHITECTURE-CODE-SPLITTING.md
      • packages/router-plugin/src/core/code-splitter/compilers.ts
      • packages/router-plugin/src/core/router-code-splitter-plugin.ts
      • packages/router-plugin/tests/add-hmr.test.ts
      • packages/router-plugin/tests/code-splitter.test.ts
      • packages/router-plugin/tests/code-splitter/snapshots/react/1-default/shared-identifier-options.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/react/1-default/shared-identifier-options@component.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/react/1-default/shared-identifier-options@errorComponent.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/react/1-default/shared-identifier-options@notFoundComponent.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/react/1-default/shared-identifier-options@shared.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/react/2-components-combined-loader-separate/shared-identifier-options.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/react/2-components-combined-loader-separate/shared-identifier-options@component---errorComponent---notFoundComponent---pendingComponent.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/react/2-components-combined-loader-separate/shared-identifier-options@loader.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/react/2-components-combined-loader-separate/shared-identifier-options@shared.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/react/3-all-combined-errorComponent-separate/shared-identifier-options.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/react/3-all-combined-errorComponent-separate/shared-identifier-options@component---loader---notFoundComponent---pendingComponent.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/react/3-all-combined-errorComponent-separate/shared-identifier-options@errorComponent.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/react/3-all-combined-errorComponent-separate/shared-identifier-options@shared.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/solid/1-default/shared-identifier-options.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/solid/1-default/shared-identifier-options@component.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/solid/1-default/shared-identifier-options@errorComponent.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/solid/1-default/shared-identifier-options@notFoundComponent.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/solid/1-default/shared-identifier-options@shared.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/solid/2-components-combined-loader-separate/shared-identifier-options.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/solid/2-components-combined-loader-separate/shared-identifier-options@component---errorComponent---notFoundComponent---pendingComponent.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/solid/2-components-combined-loader-separate/shared-identifier-options@loader.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/solid/2-components-combined-loader-separate/shared-identifier-options@shared.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/solid/3-all-combined-errorComponent-separate/shared-identifier-options.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/solid/3-all-combined-errorComponent-separate/shared-identifier-options@component---loader---notFoundComponent---pendingComponent.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/solid/3-all-combined-errorComponent-separate/shared-identifier-options@errorComponent.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/solid/3-all-combined-errorComponent-separate/shared-identifier-options@shared.tsx
      • packages/router-plugin/tests/code-splitter/test-files/react/shared-identifier-options.tsx
      • packages/router-plugin/tests/code-splitter/test-files/solid/shared-identifier-options.tsx
      • packages/router-plugin/tests/detect-route-codesplit-groupings.test.ts
      • packages/router-plugin/tests/reference-pipeline.test.ts
      • packages/router-plugin/tests/shared-bindings-helpers.test.ts
      💤 Files with no reviewable changes (8)
      • packages/router-plugin/tests/code-splitter/snapshots/react/3-all-combined-errorComponent-separate/shared-identifier-options@errorComponent.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/solid/3-all-combined-errorComponent-separate/shared-identifier-options@errorComponent.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/react/1-default/shared-identifier-options@errorComponent.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/solid/1-default/shared-identifier-options@errorComponent.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/solid/1-default/shared-identifier-options@notFoundComponent.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/react/1-default/shared-identifier-options@notFoundComponent.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/solid/3-all-combined-errorComponent-separate/shared-identifier-options@shared.tsx
      • packages/router-plugin/tests/code-splitter/snapshots/react/3-all-combined-errorComponent-separate/shared-identifier-options@shared.tsx
      🚧 Files skipped from review as they are similar to previous changes (2)
      • .changeset/quick-dingos-decide.md
      • packages/router-plugin/ARCHITECTURE-CODE-SPLITTING.md

      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 parses each reference route once and reuses its AST for grouping detection, shared-binding analysis, and compilation. The change adds AST-based compiler APIs and updates tests, React and Solid fixtures, snapshots, architecture documentation, and the patch changeset.

      Changes

      Single-parse route pipeline

      Layer / File(s)Summary
      AST compiler APIs
      packages/router-plugin/src/core/code-splitter/compilers.ts
      Grouping detection and shared-binding analysis now consume ASTs. Reference-route compilation has an AST-based implementation and a parsing wrapper.
      Plugin single-parse flow
      packages/router-plugin/src/core/router-code-splitter-plugin.ts, packages/router-plugin/ARCHITECTURE-CODE-SPLITTING.md, .changeset/quick-dingos-decide.md
      The reference-file handler parses route source once and passes the AST through analysis and compilation. The architecture documentation and changeset describe the updated flow.
      AST pipeline validation
      packages/router-plugin/tests/add-hmr.test.ts, packages/router-plugin/tests/code-splitter.test.ts, packages/router-plugin/tests/detect-route-codesplit-groupings.test.ts, packages/router-plugin/tests/shared-bindings-helpers.test.ts, packages/router-plugin/tests/reference-pipeline.test.ts
      Tests exercise AST-based analysis and compilation, including grouping and binding expectations, parity, source maps, HMR, compiler hooks, and pipeline behavior.
      Shared-identifier split fixtures
      packages/router-plugin/tests/code-splitter/test-files/*, packages/router-plugin/tests/code-splitter/snapshots/react/*, packages/router-plugin/tests/code-splitter/snapshots/solid/*
      React and Solid fixtures and snapshots cover shared bindings across separate component and loader groups and generated split outputs.

      Priority: ➖ Normal

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

      Change: Refactor

      Suggested reviewers: schiller-manuel

      Merge Risk: ⚪ Minimal · up to 52c37

      The single-parse change is mergeable after normal checks; no specific behavior requiring correction remains established.

      Security Architecture Review

      Security architecture risk: 🔵 Low · up to 52c37

      The change appears confined to build-time route compilation. The existing route input and compiler-extension boundaries remain in place, and no new security exposure was identified. Coverage is incomplete, so the assessment is low risk rather than a claim of complete safety.

      Retained concerns No architecture-level concerns identified.

      Security review details

      Security Blast Radius

      • inferred — The assessed change affects build-time processing of route source within the router plugin, without an observed new package-level entrypoint or cross-service path.

      Trust Boundaries and Controls

      • inferred — Route source reaches the existing transform and grouping validation before compiler mutation. Configured compiler hooks still receive their existing compilation contexts; the AST entrypoint does not establish a new hook authority boundary.

      Resilience and Maintainability Implications

      • inferred — Fresh parsing per reference transform and independent parsing for shared output limit reuse of a mutated AST across operations. A repeated-HMR runtime trace was not available.
      🚥 Pre-merge checks | ✅ 4 | ❌ 1

      ❌ Failed checks (1 warning)

      Check nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring coverage is 43.75% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 16 functions across 28 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 primary performance change: parsing reference routes once.
      Description check✅ PassedThe description is detailed and relevant. It explains the change, motivation, performance results, validation, tests, and release impact. It does not reproduce the template headings or checklist, but …
      Full details: Docstring Coverage

      Explanation

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

      • Fix all pre-merge checks with AI
      ✨ Finishing Touches 💡 1
      📝 Generate docstrings 💡
      • Create stacked PR
      • Commit on current branch
      🧪 Generate unit tests (beta)
      • Commit to this branch
      • Create a new PR

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

      CommandStatusDurationResult
      nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded16m 41sView ↗
      nx run-many --target=build --exclude=examples/*...✅ Succeeded1m 36sView ↗

      ☁️ Nx Cloud last updated this comment at 2026-09-26 20:49:15 UTC

    4. 🚀 Changeset Version Preview

      7 package(s) bumped directly, 16 bumped as dependents.

      🟩 Patch bumps

      PackageVersionReason
      @tanstack/react-router1.170.39 → 1.170.40Changeset
      @tanstack/router-core1.171.32 → 1.171.33Changeset
      @tanstack/router-plugin1.168.40 → 1.168.41Changeset
      @tanstack/solid-router1.170.36 → 1.170.37Changeset
      @tanstack/start-client-core1.170.32 → 1.170.33Changeset
      @tanstack/start-server-core1.169.37 → 1.169.38Changeset
      @tanstack/vue-router1.170.35 → 1.170.36Changeset
      @tanstack/react-start1.168.58 → 1.168.59Dependent
      @tanstack/react-start-client1.168.37 → 1.168.38Dependent
      @tanstack/react-start-rsc0.1.57 → 0.1.58Dependent
      @tanstack/react-start-server1.167.44 → 1.167.45Dependent
      @tanstack/router-cli1.167.38 → 1.167.39Dependent
      @tanstack/router-generator1.167.38 → 1.167.39Dependent
      @tanstack/router-vite-plugin1.167.40 → 1.167.41Dependent
      @tanstack/solid-start1.168.55 → 1.168.56Dependent
      @tanstack/solid-start-client1.168.35 → 1.168.36Dependent
      @tanstack/solid-start-server1.167.42 → 1.167.43Dependent
      @tanstack/start-plugin-core1.171.47 → 1.171.48Dependent
      @tanstack/start-static-server-functions1.167.37 → 1.167.38Dependent
      @tanstack/start-storage-context1.167.34 → 1.167.35Dependent
      @tanstack/vue-start1.168.54 → 1.168.55Dependent
      @tanstack/vue-start-client1.167.38 → 1.167.39Dependent
      @tanstack/vue-start-server1.167.42 → 1.167.43Dependent
    5. Bundle Size Benchmarks

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

    6. More templates

      @tanstack/arktype-adapter

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

      @tanstack/eslint-plugin-router

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

      @tanstack/eslint-plugin-start

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

      @tanstack/history

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

      @tanstack/nitro-v2-vite-plugin

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

      @tanstack/react-router

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

      @tanstack/react-router-devtools

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

      @tanstack/react-router-ssr-query

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

      @tanstack/react-start

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

      @tanstack/react-start-client

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

      @tanstack/react-start-rsc

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

      @tanstack/react-start-server

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

      @tanstack/router-cli

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

      @tanstack/router-core

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

      @tanstack/router-devtools

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

      @tanstack/router-devtools-core

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

      @tanstack/router-generator

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

      @tanstack/router-plugin

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

      @tanstack/router-ssr-query-core

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

      @tanstack/router-utils

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

      @tanstack/router-vite-plugin

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

      @tanstack/solid-router

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

      @tanstack/solid-router-devtools

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

      @tanstack/solid-router-ssr-query

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

      @tanstack/solid-start

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

      @tanstack/solid-start-client

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

      @tanstack/solid-start-server

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

      @tanstack/start-client-core

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

      @tanstack/start-fn-stubs

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

      @tanstack/start-plugin-core

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

      @tanstack/start-server-core

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

      @tanstack/start-static-server-functions

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

      @tanstack/start-storage-context

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

      @tanstack/valibot-adapter

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

      @tanstack/virtual-file-routes

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

      @tanstack/vue-router

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

      @tanstack/vue-router-devtools

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

      @tanstack/vue-router-ssr-query

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

      @tanstack/vue-start

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

      @tanstack/vue-start-client

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

      @tanstack/vue-start-server

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

      @tanstack/zod-adapter

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

      commit: 52c37b5

    7. packages/router-plugin/tests/reference-pipeline.bench.ts line 13Outdated
      @@ -0,0 +1,13 @@
      1+import { bench, describe, expect } from 'vitest'
      2+import { parseAst } from '@tanstack/router-utils'
      3+import {
      4+ compileCodeSplitReferenceRoute,
      5+ compileCodeSplitReferenceRouteFromAst,
      6+ computeSharedBindings,
      7+ computeSharedBindingsFromAst,
      8+ detectCodeSplitGroupingsFromAst,
      9+ detectCodeSplitGroupingsFromRoute,
      10+} from '../src/core/code-splitter/compilers'
      11+import { defaultCodeSplitGroupings } from '../src/core/constants'
      12+
      13+// Compare the old three-parse pipeline with the plugin's one-parse pipeline.

      should we keep this bench? probably not?

    8. Merging this PR will not alter performance

      ✅ 191 untouched benchmarks ⏩ 3 skipped benchmarks1


      Comparing perf/router-reference-parse-once (52c37b5) with main (7471fb8) 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. ↩

    9. packages/router-plugin/src/core/router-code-splitter-plugin.ts line 14
      @@ -4,11 +4,9 @@
      44 */
      55
      66 import { fileURLToPath, pathToFileURL } from 'node:url'
      7-import { decodeIdentifier, logDiff } from '@tanstack/router-utils'
      7+import { decodeIdentifier, logDiff, parseAst } from '@tanstack/router-utils'
      88 import { getConfig, splitGroupingsSchema } from './config'
      99 import {
      10- compileCodeSplitReferenceRoute,
      10+ compileCodeSplitReferenceRouteFromAst,
      1111 compileCodeSplitSharedRoute,
      1212 compileCodeSplitVirtualRoute,
      13- computeSharedBindings,
      14- detectCodeSplitGroupingsFromRoute,

      are those functions still used (outside of tests)? we should not keep them if not used, dont shim them etc.

    10. schiller-manuel(GitHub profile, opens in a new tab) approved these changes

Sign in to join this conversation.