perf(compiler): reuse immutable cleanup metadata across outputs #8540
codex/direct-compiler-ast fromcodex/immutable-cleanup-metadata·opened 🎯 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'sRouteModuleAnalysisand Hydrate'sSourceEntry. - Reuse the declaration-symbol map as the owner lookup instead of copying it.
- Keep standalone
removeUnusedBindingsmetadata 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 groups | Baseline → candidate median | Change | Faster pairs |
|---|---|---|---|
| 64 / 2 / 4 | 664 → 658 ms | -1.0% | 8/11 |
| 64 / 12 / 1 | 1,347 → 1,321 ms | -2.0% | 7/11 |
| 64 / 12 / 4 | 1,957 → 1,884 ms | -3.8% | 10/11 |
| Same case, independent confirmation | 2,011 → 1,947 ms | -3.2% | 10/11 |
| 192 / 12 / 4 | 5,831 → 5,855 ms | +0.4% | 6/11 |
| 64 / 48 / 4 | 7,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
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-plugin
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-utils
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: start-plugin-core
View your CI Pipeline Execution ↗ for commit 3010042b6b9aec05502f7a690b29aed36b3b11cd
Command Status Duration Result nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded 18m View ↗ nx run-many --target=build --exclude=examples/*...✅ Succeeded 1m 25s View ↗
☁️ Nx Cloud last updated this comment at
2026-09-27 23:53:53UTC🚀 Changeset Version Preview#
6 package(s) bumped directly, 7 bumped as dependents.
🟥 Major bumps#
Package Version Reason @tanstack/router-plugin1.168.41 → 2.0.0 Changeset @tanstack/router-utils1.162.3 → 2.0.0 Changeset @tanstack/start-plugin-core1.171.48 → 2.0.0 Changeset 🟩 Patch bumps#
Package Version Reason @tanstack/react-router1.170.40 → 1.170.41 Changeset @tanstack/react-start-rsc0.1.58 → 0.1.59 Changeset @tanstack/router-generator1.167.39 → 1.167.40 Changeset @tanstack/react-start1.168.59 → 1.168.60 Dependent @tanstack/react-start-client1.168.38 → 1.168.39 Dependent @tanstack/react-start-server1.167.45 → 1.167.46 Dependent @tanstack/router-cli1.167.39 → 1.167.40 Dependent @tanstack/router-vite-plugin1.167.41 → 1.167.42 Dependent @tanstack/solid-start1.168.56 → 1.168.57 Dependent @tanstack/vue-start1.168.55 → 1.168.56 Dependent 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-vue-example-basic-jsx
- tanstack-router-vue-example-basic-file-based-jsx
- tanstack-router-vue-example-basic-file-based-sfc
- 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/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@8540commit:
3010042Bundle Size Benchmarks#
This pull request does not affect bundle size in any measured scenario.
Merging this PR will not alter performance#
✅ 191untouched benchmarks⏩ 3skipped benchmarks1
Comparingcodex/immutable-cleanup-metadata(3010042) withcodex/direct-compiler-ast(c6c33e2)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.
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.mdbenchmarks/compiler/README.mdbenchmarks/compiler/RESULT-optimization-cleanup-metadata.mdbenchmarks/compiler/cleanup-build.mdbenchmarks/compiler/cleanup-build.mjsbenchmarks/compiler/cleanup-hydrate.mjsbenchmarks/compiler/cleanup.mjsbenchmarks/compiler/results/cleanup-attribution.jsonbenchmarks/compiler/results/cleanup-build-r192-h12-g4-diagnostic.jsonbenchmarks/compiler/results/cleanup-build-r192-h12-g4.jsonbenchmarks/compiler/results/cleanup-build-r64-h12-g1-diagnostic.jsonbenchmarks/compiler/results/cleanup-build-r64-h12-g1.jsonbenchmarks/compiler/results/cleanup-build-r64-h12-g4-confirmation.jsonbenchmarks/compiler/results/cleanup-build-r64-h12-g4-diagnostic.jsonbenchmarks/compiler/results/cleanup-build-r64-h12-g4.jsonbenchmarks/compiler/results/cleanup-build-r64-h2-g4-diagnostic.jsonbenchmarks/compiler/results/cleanup-build-r64-h2-g4.jsonbenchmarks/compiler/results/cleanup-build-r64-h48-g4-diagnostic.jsonbenchmarks/compiler/results/cleanup-build-r64-h48-g4.jsonbenchmarks/compiler/results/cleanup-build-summary.jsonbenchmarks/compiler/results/cleanup-bundle-baseline.jsonbenchmarks/compiler/results/cleanup-bundle-cache-only.jsonbenchmarks/compiler/results/cleanup-bundle-candidate.jsonbenchmarks/compiler/results/cleanup-bundle-copy-only.jsonbenchmarks/compiler/results/cleanup-bundle-final.jsonbenchmarks/compiler/results/cleanup-bundle-hashes.jsonbenchmarks/compiler/results/cleanup-diagnostics.jsonbenchmarks/compiler/results/cleanup-focused-attribution.jsonbenchmarks/compiler/results/cleanup-focused.jsonbenchmarks/compiler/results/cleanup-hydrate.jsonbenchmarks/compiler/results/cleanup-start-digests.jsonbenchmarks/compiler/results/cleanup-start.jsonbenchmarks/compiler/results/cleanup-weakmap-start.jsonbenchmarks/compiler/results/cleanup-whole.jsonpackages/router-plugin/src/core/code-splitter/compilers.tspackages/router-utils/src/compiler-helpers.tspackages/router-utils/src/index.tspackages/router-utils/tests/compiler-helpers.test-d.tspackages/router-utils/tests/compiler-helpers.test.tspackages/start-plugin-core/src/hydrate-when-transform.tspackages/start-plugin-core/tests/hydrate-when-transform.test.tsIncluded 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
packages/router-utils/src/compiler-helpers.ts,packages/router-utils/src/index.ts,packages/router-utils/tests/compiler-helpers.test*,.changeset/plain-carrots-enjoy.mdcreateBindingCleanup. It retains cleanup metadata for repeated calls;removeUnusedBindingscontinues to create fresh metadata per call. Tests cover output-specific liveness and declaration retention.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.tsbenchmarks/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.jsonbenchmarks/compiler/cleanup-build.mjs,benchmarks/compiler/cleanup-build.md,benchmarks/compiler/README.md,benchmarks/compiler/results/cleanup-build-*.jsonbenchmarks/compiler/results/cleanup-bundle-*.jsonPriority: ⬇️ Low
Estimated code review effort: 4 (Complex) | ~45 minutes
Merge Risk: ⚪ Minimal · up to
30100No actionable issue is established that should prevent merging after normal checks.
Security Architecture Review#
Security architecture risk: 🔵 Low · up to
30100The 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
Trust Boundaries and Controls
Resilience and Maintainability Implications
Hardening Proposals
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)#
✅ Passed checks (4 passed)
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.)
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
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