Skip to content
Source
Sign inSign up
TanStack/router

perf(compiler): reuse immutable cleanup metadata across outputs #8540

OpenSheraff(GitHub profile, opens in a new tab)wants to merge 2 commits intocodex/direct-compiler-ast fromcodex/immutable-cleanup-metadataopened

🎯 Changes

Route and Hydrate sibling outputs currently rebuild the same source declaration indexes and export membership during each cleanup. Retain that immutable metadata with the existing source analysis, while rebuilding liveness and dependencies for every edited output.

Stacked on #8524: this PR targets codex/direct-compiler-ast at c6c33e2285. It does not modify that PR's branch. Implements the “Carry immutable cleanup metadata across outputs” idea from the compiler follow-up.

  • Add a lazy createBindingCleanup(module) factory owned by Router's RouteModuleAnalysis and Hydrate's SourceEntry.
  • Reuse the declaration-symbol map as the owner lookup instead of copying it.
  • Keep standalone removeUnusedBindings metadata local to each call.
  • Cover independently edited siblings, generated references, merged declarations, repeated cleanup, and source replacement. Add reproducible benchmarks and raw measurements in a separate commit from the implementation.

Measured performance

Baseline is unchanged #8524. Measurements use Node 24.8.0 on an Apple M3 Max, identical inputs, separately built checkouts, and serialized fresh processes with alternating baseline/candidate order.

Focused cleanup of five sibling outputs improves 13.3% for small routes, 14.2% for nested declarations, and 6.8% for wide sources. One-off Start compiler results are effectively unchanged: client -0.2%, SSR -0.8%, provider +0.8%, within process variation. Compiling a parent and ten distinct Hydrate children improves 23.7%; the one-, two-, and 25-child cases are noisier. These compiler measurements are not application-build or hydration-latency percentages.

Complete Vite production builds include route generation, transforms, bundling, minification, source maps, and writes. Each row below is 11 fresh process pairs. Helpers are per loader/component/pending/error pipeline; the 48-helper case is a large-source stress fixture.

Routes / helpers / split groupsBaseline → candidate medianChangeFaster pairs
64 / 2 / 4664 → 658 ms-1.0%8/11
64 / 12 / 11,347 → 1,321 ms-2.0%7/11
64 / 12 / 41,957 → 1,884 ms-3.8%10/11
Same case, independent confirmation2,011 → 1,947 ms-3.2%10/11
192 / 12 / 45,831 → 5,855 ms+0.4%6/11
64 / 48 / 47,017 → 6,573 ms-6.3%9/11

The supported whole-build gain is about 3–4% for declaration-heavy, multi-output sources whose analyses survive until sibling requests arrive: 20/22 pairs improve across the two batches. Diagnostics show 384 cleanups sharing 64 metadata constructions, down from 384. Generated JavaScript is identical in all comparisons.

Caveats and memory

  • Small modules, one split group, and cache overflow do not establish a reliable whole-build gain. The stress case has large timing swings and an uncertainty interval spanning zero; its favorable median alone is not a demonstrated 6% improvement. The confirmation batch is also noisier than the initial batch. These are controlled Router workloads, not a general application or complete Start build guarantee.
  • Earlier broad 64/250/750-route builds measured -2.0% / -1.1% / +0.1%, with small/noisy differences. The complete compiler corpus measured -4.6%, with roughly 4.5% process CV. Benchmarks exclude package-build orchestration and TypeScript checking; filesystem caches are warm.
  • The positive whole-build case retains approximately 5.3 MiB more heap while its source cache is live. Peak process RSS rises 31–34 MiB across the two batches; GC/native allocation and allocator high-water marks also affect RSS. The large-source stress fixture retains about 20 MiB more cache heap. This is a speed/memory tradeoff.
  • Metadata follows source-cache lifetime, not last-sibling completion. Router releases ownership on LRU eviction, source replacement, or buildEnd(), before output rendering/minification/writes. All tracked analyses become collectible after that clear in the diagnostics. Hydrate retains metadata until source invalidation/replacement or plugin collection; it has no equivalent build-end clear and may retain it beyond a build while the plugin remains alive.

Full compiler evaluation and raw results · Whole-build conditions, uncertainty, and lifetime

Validation already completed

Before PR preparation: 1,423 unit/type tests, 196 browser tests, package TypeScript/ESLint/build checks, and the full 18-scenario bundle comparison passed. All 38 emitted client JavaScript files were byte-identical. The follow-up benchmark verified 132 timed and ten diagnostic complete builds. No checks were rerun when opening this PR; CI will provide the current commit results.

✅ 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).

Patch changesets for @tanstack/router-utils, @tanstack/router-plugin, and @tanstack/start-plugin-core.

Summary by CodeRabbit

  • Performance

    • Compiler outputs now reuse source analysis while independently determining which code each output needs. This can reduce repeated compiler work, with build-time improvements varying by project.
    • Bundle comparisons showed no change to generated bundle contents or sizes.
  • Bug Fixes

    • Fixed cases where sibling hydration boundaries could produce incorrect virtual-module contents when reusing or changing source imports.
    1. 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: 9a599d78-19bc-47ec-bd50-22efbf63f085

      📥 Commits

      Reviewing files that changed from the base of the PR and between c6c33e22857cdefcad00e217201f05e5bcd39551 and 3010042b6b9aec05502f7a690b29aed36b3b11cd.

      📒 Files selected for processing (41)
      • .changeset/plain-carrots-enjoy.md
      • benchmarks/compiler/README.md
      • benchmarks/compiler/RESULT-optimization-cleanup-metadata.md
      • benchmarks/compiler/cleanup-build.md
      • benchmarks/compiler/cleanup-build.mjs
      • benchmarks/compiler/cleanup-hydrate.mjs
      • benchmarks/compiler/cleanup.mjs
      • benchmarks/compiler/results/cleanup-attribution.json
      • benchmarks/compiler/results/cleanup-build-r192-h12-g4-diagnostic.json
      • benchmarks/compiler/results/cleanup-build-r192-h12-g4.json
      • benchmarks/compiler/results/cleanup-build-r64-h12-g1-diagnostic.json
      • benchmarks/compiler/results/cleanup-build-r64-h12-g1.json
      • benchmarks/compiler/results/cleanup-build-r64-h12-g4-confirmation.json
      • benchmarks/compiler/results/cleanup-build-r64-h12-g4-diagnostic.json
      • benchmarks/compiler/results/cleanup-build-r64-h12-g4.json
      • benchmarks/compiler/results/cleanup-build-r64-h2-g4-diagnostic.json
      • benchmarks/compiler/results/cleanup-build-r64-h2-g4.json
      • benchmarks/compiler/results/cleanup-build-r64-h48-g4-diagnostic.json
      • benchmarks/compiler/results/cleanup-build-r64-h48-g4.json
      • benchmarks/compiler/results/cleanup-build-summary.json
      • benchmarks/compiler/results/cleanup-bundle-baseline.json
      • benchmarks/compiler/results/cleanup-bundle-cache-only.json
      • benchmarks/compiler/results/cleanup-bundle-candidate.json
      • benchmarks/compiler/results/cleanup-bundle-copy-only.json
      • benchmarks/compiler/results/cleanup-bundle-final.json
      • benchmarks/compiler/results/cleanup-bundle-hashes.json
      • benchmarks/compiler/results/cleanup-diagnostics.json
      • benchmarks/compiler/results/cleanup-focused-attribution.json
      • benchmarks/compiler/results/cleanup-focused.json
      • benchmarks/compiler/results/cleanup-hydrate.json
      • benchmarks/compiler/results/cleanup-start-digests.json
      • benchmarks/compiler/results/cleanup-start.json
      • benchmarks/compiler/results/cleanup-weakmap-start.json
      • benchmarks/compiler/results/cleanup-whole.json
      • packages/router-plugin/src/core/code-splitter/compilers.ts
      • packages/router-utils/src/compiler-helpers.ts
      • packages/router-utils/src/index.ts
      • packages/router-utils/tests/compiler-helpers.test-d.ts
      • packages/router-utils/tests/compiler-helpers.test.ts
      • packages/start-plugin-core/src/hydrate-when-transform.ts
      • packages/start-plugin-core/tests/hydrate-when-transform.test.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.


      📝 Walkthrough

      Walkthrough

      The change adds a reusable cleanup callback that retains source binding metadata while recalculating liveness for each output. Router and Hydrate compilation use the callback. New benchmark scripts, documentation, and result records measure cleanup, build, memory, and bundle outputs.

      Changes

      Binding Cleanup Metadata Reuse

      Layer / File(s)Summary
      Reusable cleanup API and liveness tests
      packages/router-utils/src/compiler-helpers.ts, packages/router-utils/src/index.ts, packages/router-utils/tests/compiler-helpers.test*, .changeset/plain-carrots-enjoy.md
      Adds and exports createBindingCleanup. It retains cleanup metadata for repeated calls; removeUnusedBindings continues to create fresh metadata per call. Tests cover output-specific liveness and declaration retention.
      Router and Hydrate cleanup integration
      packages/router-plugin/src/core/code-splitter/compilers.ts, packages/start-plugin-core/src/hydrate-when-transform.ts, packages/start-plugin-core/tests/hydrate-when-transform.test.ts
      Router analyses and Hydrate source entries store cleanup callbacks and use them when generating outputs. Hydrate tests check separate virtual-module output for sibling boundaries.
      Cleanup and Hydrate benchmark coverage
      benchmarks/compiler/cleanup.mjs, benchmarks/compiler/cleanup-hydrate.mjs, benchmarks/compiler/README.md, benchmarks/compiler/RESULT-optimization-cleanup-metadata.md, benchmarks/compiler/results/cleanup-attribution.json, benchmarks/compiler/results/cleanup-diagnostics.json, benchmarks/compiler/results/cleanup-start-digests.json
      Adds cleanup and Hydrate benchmarks, documents their workloads and measurement boundaries, and records timing, memory, and output measurements.
      Complete-build benchmark and results
      benchmarks/compiler/cleanup-build.mjs, benchmarks/compiler/cleanup-build.md, benchmarks/compiler/README.md, benchmarks/compiler/results/cleanup-build-*.json
      Adds a configurable Vite build benchmark with output checks and optional diagnostics. Documentation and results record paired baseline and candidate measurements across workload configurations.
      Bundle comparison records
      benchmarks/compiler/results/cleanup-bundle-*.json
      Adds bundle size results and hashes for React, Solid, and Vue scenarios.

      Priority: ⬇️ Low

      Estimated code review effort: 4 (Complex) | ~45 minutes

      Merge Risk: ⚪ Minimal · up to 30100

      No actionable issue is established that should prevent merging after normal checks.

      Security Architecture Review

      Security architecture risk: 🔵 Low · up to 30100

      The reviewed compiler paths keep output-specific cleanup separate from reusable source metadata. No introduced security exposure was identified, but generated-bundle behavior was not independently verified.

      Retained concerns No architecture-level concerns identified.

      Security review details

      Security Blast Radius

      • inferred — The relevant exposure is generated route and Hydrate output across compiler consumers, not a newly identified runtime request, credential, or service-authority path. Dependency evidence for downstream consumers is capped, so the complete consumer set is not established here.

      Trust Boundaries and Controls

      • observed — Generated outputs are cloned from their source modules before the retained callback runs. Hydrate keeps its callback with the corresponding source entry and replaces that entry when its source changes; the factory itself has no runtime source/provenance check.

      Resilience and Maintainability Implications

      • inferred — Per-call mutable cleanup state and synchronous execution limit cross-output state leakage. Recovery using a fresh clone follows the inspected call pattern; recovery on the same partially modified AST remains unverified.

      Hardening Proposals

      • proposed — Compare emitted client and server bundles after compiling several siblings from one source analysis, particularly for imports intended to remain server-only. This would test the security-relevant output boundary beyond source-level equivalence tests.
      🚥 Pre-merge checks | ✅ 4 | ❌ 1

      ❌ Failed checks (1 warning)

      Check nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring coverage is 11.11% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 18 functions across 10 files. (24 skipped…Write docstrings for the functions missing them to satisfy the coverage threshold.
      ✅ Passed checks (4 passed)
      Check nameStatusExplanation
      Title check✅ PassedThe title clearly and concisely describes the main performance change: reusing immutable compiler cleanup metadata across outputs.
      Description check✅ PassedThe description is complete. It explains the change and motivation, documents performance and memory tradeoffs, lists validation results, completes the checklist, and identifies the release impact and…
      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.
      Full details: Docstring Coverage

      Explanation

      Docstring coverage is 11.11% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 18 functions across 10 files. (24 skipped: 24 unsupported.)

      • Fix all pre-merge checks with AI
      ✨ 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

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

    3. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-utils

    4. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: start-plugin-core

    5. View your CI Pipeline Execution ↗ for commit 3010042b6b9aec05502f7a690b29aed36b3b11cd

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

      ☁️ Nx Cloud last updated this comment at 2026-09-27 23:53:53 UTC

    6. 🚀 Changeset Version Preview

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

      🟥 Major bumps

      PackageVersionReason
      @tanstack/router-plugin1.168.41 → 2.0.0Changeset
      @tanstack/router-utils1.162.3 → 2.0.0Changeset
      @tanstack/start-plugin-core1.171.48 → 2.0.0Changeset

      🟩 Patch bumps

      PackageVersionReason
      @tanstack/react-router1.170.40 → 1.170.41Changeset
      @tanstack/react-start-rsc0.1.58 → 0.1.59Changeset
      @tanstack/router-generator1.167.39 → 1.167.40Changeset
      @tanstack/react-start1.168.59 → 1.168.60Dependent
      @tanstack/react-start-client1.168.38 → 1.168.39Dependent
      @tanstack/react-start-server1.167.45 → 1.167.46Dependent
      @tanstack/router-cli1.167.39 → 1.167.40Dependent
      @tanstack/router-vite-plugin1.167.41 → 1.167.42Dependent
      @tanstack/solid-start1.168.56 → 1.168.57Dependent
      @tanstack/vue-start1.168.55 → 1.168.56Dependent
    7. More templates

      @tanstack/arktype-adapter

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

      @tanstack/eslint-plugin-router

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

      @tanstack/eslint-plugin-start

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

      @tanstack/history

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

      @tanstack/nitro-v2-vite-plugin

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

      @tanstack/react-router

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

      @tanstack/react-router-devtools

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

      @tanstack/react-router-ssr-query

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

      @tanstack/react-start

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

      @tanstack/react-start-client

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

      @tanstack/react-start-rsc

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

      @tanstack/react-start-server

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

      @tanstack/router-cli

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

      @tanstack/router-core

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

      @tanstack/router-devtools

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

      @tanstack/router-devtools-core

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

      @tanstack/router-generator

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

      @tanstack/router-plugin

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

      @tanstack/router-ssr-query-core

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

      @tanstack/router-utils

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

      @tanstack/router-vite-plugin

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

      @tanstack/solid-router

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

      @tanstack/solid-router-devtools

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

      @tanstack/solid-router-ssr-query

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

      @tanstack/solid-start

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

      @tanstack/solid-start-client

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

      @tanstack/solid-start-server

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

      @tanstack/start-client-core

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

      @tanstack/start-fn-stubs

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

      @tanstack/start-plugin-core

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

      @tanstack/start-server-core

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

      @tanstack/start-static-server-functions

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

      @tanstack/start-storage-context

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

      @tanstack/valibot-adapter

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

      @tanstack/virtual-file-routes

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

      @tanstack/vue-router

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

      @tanstack/vue-router-devtools

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

      @tanstack/vue-router-ssr-query

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

      @tanstack/vue-start

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

      @tanstack/vue-start-client

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

      @tanstack/vue-start-server

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

      @tanstack/zod-adapter

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

      commit: 3010042

    8. Bundle Size Benchmarks

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

    9. Merging this PR will not alter performance

      ✅ 191 untouched benchmarks ⏩ 3 skipped benchmarks1


      Comparing codex/immutable-cleanup-metadata (3010042) with codex/direct-compiler-ast (c6c33e2) 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.