Skip to content
Source
Sign inSign up
TanStack/router

perf(start): construct compiler-owned server function AST directly #8524

OpenSheraff(GitHub profile, opens in a new tab)wants to merge 1 commit intocodex/fuse-clone-provenance fromcodex/direct-compiler-astopened

🎯 Changes

Stacks on #8523; base branch: codex/fuse-clone-provenance.

Server-function compilation currently reparses compiler-owned JavaScript snippets for RPC calls, provider wrappers, imports, directives, and HMR guards. Construct those nodes directly with typed AST builders, preserving generated-reference ownership, source maps, and emitted code.

Compound builders live in named functions with readable inline snapshots of their generated JavaScript. Additional execution tests cover client/SSR/provider output across React, Solid, and Vue, escaping, binding cleanup, HMR, and invalidation.

Measured performance

Complete generated React Start production builds, with 10 server functions per module and seven alternating fresh-process pairs per size:

Server functions#8523 medianThis change medianReductionPeak RSS, before → after
100333.07 ms326.33 msWithin noise329.8 → 324.2 MiB
1,000886.94 ms813.09 ms8.3%519.9 → 483.2 MiB
5,0006,682.98 ms6,048.85 ms9.5%883.8 → 849.5 MiB

The candidate wins all seven pairs at 1,000 and 5,000 functions. The 5,000-function fixture is a stress case. Timings include Vite builder creation, transformation, bundling, minification, and writes; they exclude fixture generation, plugin-module loading, and output validation. All RPCs and handlers are retained; client output is byte-identical and server output matches after normalizing build paths and chunk filenames.

Focused compiler measurements show 15.0% faster client transforms, 19.9% faster SSR callers, 27.7% faster providers, and 29.3% faster development providers. The existing smaller e2e app's whole-build result was inconclusive (950.26 → 962.54 ms), so these gains should not be generalized to every app.

Measured on Node 24.8.0 / Apple M3 Max against #8523 at 6c228b37ad, with the extracted candidate on 9148909cc5. The current stack base 3dfc160aee only adds Solid CSS test changes. Full methodology, raw results, and attribution.

Previously completed validation

  • 608 compiler tests and 165 browser tests; TypeScript 5.6–7, ESLint, and package build/export checks passed.
  • The latest inline-snapshot-only edit passed all eight builder tests.
  • All 18 bundle scenarios have zero size/chunk-count changes; all 38 emitted client JS files are byte-identical.
  • No checks were rerun when opening this PR; CI will validate the published branch.

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

Summary by CodeRabbit

  • Performance
    • Server-function compilation and production builds now run faster in several benchmarked workloads, while preserving equivalent generated output.
  • Reliability
    • Added checks for generated server-function output across React, Solid, and Vue, including client, server-rendering, provider, and development scenarios.
  • Documentation
    • Added guidance and results for compiler and production-build benchmarks.
    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: 605f17db-53a0-4dec-b85e-2831bde04fcc

      📥 Commits

      Reviewing files that changed from the base of the PR and between 080a540029f7445471be451f1ace27ee4eeedabf and c6c33e22857cdefcad00e217201f05e5bcd39551.

      📒 Files selected for processing (43)
      • .changeset/fuzzy-berries-behave.md
      • benchmarks/compiler/README.md
      • benchmarks/compiler/direct-ast.md
      • benchmarks/compiler/results/direct-ast-app-output.json
      • benchmarks/compiler/results/direct-ast-builders-digests.json
      • benchmarks/compiler/results/direct-ast-builders-timings.json
      • benchmarks/compiler/results/direct-ast-builds.json
      • benchmarks/compiler/results/direct-ast-bundle-baseline-hashes.json
      • benchmarks/compiler/results/direct-ast-bundle-baseline.json
      • benchmarks/compiler/results/direct-ast-bundle-builders-final-hashes.json
      • benchmarks/compiler/results/direct-ast-bundle-builders-final.json
      • benchmarks/compiler/results/direct-ast-bundle-final-hashes.json
      • benchmarks/compiler/results/direct-ast-bundle-final.json
      • benchmarks/compiler/results/direct-ast-bundle-pre-attribution.json
      • benchmarks/compiler/results/direct-ast-caller-digests.json
      • benchmarks/compiler/results/direct-ast-caller-timings.json
      • benchmarks/compiler/results/direct-ast-dense-refined-timings.json
      • benchmarks/compiler/results/direct-ast-digests.json
      • benchmarks/compiler/results/direct-ast-directives-digests.json
      • benchmarks/compiler/results/direct-ast-directives-refined-timings.json
      • benchmarks/compiler/results/direct-ast-directives-timings.json
      • benchmarks/compiler/results/direct-ast-final-digests.json
      • benchmarks/compiler/results/direct-ast-final-timings.json
      • benchmarks/compiler/results/direct-ast-final-verification.json
      • benchmarks/compiler/results/direct-ast-heavy-builds-100.json
      • benchmarks/compiler/results/direct-ast-heavy-builds-1000.json
      • benchmarks/compiler/results/direct-ast-heavy-builds-5000.json
      • benchmarks/compiler/results/direct-ast-hmr-digests.json
      • benchmarks/compiler/results/direct-ast-hmr-refined-timings.json
      • benchmarks/compiler/results/direct-ast-hmr-timings.json
      • benchmarks/compiler/results/direct-ast-hunk-bundles.json
      • benchmarks/compiler/results/direct-ast-imports-digests.json
      • benchmarks/compiler/results/direct-ast-imports-refined-timings.json
      • benchmarks/compiler/results/direct-ast-imports-timings.json
      • benchmarks/compiler/results/direct-ast-provider-digests.json
      • benchmarks/compiler/results/direct-ast-provider-timings.json
      • benchmarks/compiler/results/direct-ast-timings.json
      • benchmarks/compiler/server-fn-ast.mjs
      • benchmarks/compiler/server-fn-build.mjs
      • packages/start-plugin-core/src/start-compiler/handleCreateServerFn.ts
      • packages/start-plugin-core/src/start-compiler/serverFnAst.ts
      • packages/start-plugin-core/tests/createServerFn/generated-ast.test.ts
      • packages/start-plugin-core/tests/createServerFn/serverFnAst.test.ts

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


      📝 Walkthrough

      Walkthrough

      The server-function compiler now builds generated RPC calls, provider wrappers, imports, directives, exports, and HMR statements with AST helpers. New compiler and production-build benchmark harnesses record timing, memory, output comparisons, and bundle hashes. Tests cover generated output across frameworks and runtimes.

      Changes

      Server-function AST generation and benchmarking

      Layer / File(s)Summary
      Build and integrate server-function AST nodes
      packages/start-plugin-core/src/start-compiler/serverFnAst.ts, packages/start-plugin-core/src/start-compiler/handleCreateServerFn.ts, packages/start-plugin-core/tests/createServerFn/*ast.test.ts, .changeset/fuzzy-berries-behave.md
      AST helpers create server-function callers, providers, exports, HMR checks, imports, references, and string literals. The compiler uses the helpers instead of parsing generated source strings. Tests cover output and recompilation across frameworks and runtimes.
      Measure compiler workloads
      benchmarks/compiler/server-fn-ast.mjs, benchmarks/compiler/README.md, benchmarks/compiler/direct-ast.md, benchmarks/compiler/results/direct-ast-*.json
      The compiler benchmark runs selected workloads in baseline and candidate processes, checks source hashes and optional output digests, and records timing and memory data. Documentation and results describe the workloads, measurement protocols, and comparisons.
      Measure generated production builds
      benchmarks/compiler/server-fn-build.mjs, benchmarks/compiler/direct-ast.md, benchmarks/compiler/results/direct-ast-app-output.json, benchmarks/compiler/results/direct-ast-builds.json, benchmarks/compiler/results/direct-ast-heavy-builds-*.json, benchmarks/compiler/results/direct-ast-bundle-*-hashes.json, benchmarks/compiler/results/direct-ast-hunk-bundles.json
      The build benchmark generates a temporary React Start app, checks client and server outputs, compares normalized hashes, and records build and memory metrics. The report and result files include full-build measurements and bundle comparisons.

      Priority: ➖ Normal

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

      Merge Risk: ⚪ Minimal · up to c6c33

      The server-function AST change has no identified issue that needs resolution before merging; normal checks remain appropriate.

      Security Architecture Review

      Security architecture risk: 🔵 Low · up to c6c33

      The change affects how server-function code is generated, not an identified authorization rule or deployment boundary. Tests and recorded build comparisons support equivalent output, but they do not establish equivalence for every application.

      Retained concerns No architecture-level concerns identified.

      Security review details

      Security Blast Radius

      • inferred — A generation regression could propagate to applications using server functions across the supported runtimes. The changed test ranges do not themselves add reachable production entrypoints, and the benchmark fanout does not establish production exposure.

      Trust Boundaries and Controls

      • inferred — The generated client RPC call and server provider meet at a trust boundary, but the reviewed change supplies no evidence of a new attacker-controlled input path, changed authorization control, or increased server authority. Runtime authorization behavior was not independently verified.
      🚥 Pre-merge checks | ✅ 4 | ❌ 1

      ❌ Failed checks (1 warning)

      Check nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring coverage is 9.09% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 6 files. (30 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 main change: constructing compiler-owned server-function AST directly for performance.
      Description check✅ PassedThe description follows the required template, explains the motivation and implementation, documents validation and performance results, and completes the checklist and release-impact sections.
      Full details: Docstring Coverage

      Explanation

      Docstring coverage is 9.09% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 6 files. (30 skipped: 30 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: start-plugin-core

    3. 🚀 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
    4. View your CI Pipeline Execution ↗ for commit c6c33e22857cdefcad00e217201f05e5bcd39551

      CommandStatusDurationResult
      nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded25m 52sView ↗
      nx run-many --target=build --exclude=examples/*...✅ Succeeded2m 7sView ↗

      ☁️ Nx Cloud last updated this comment at 2026-09-27 20:42:27 UTC

    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@8524

      @tanstack/eslint-plugin-router

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

      @tanstack/eslint-plugin-start

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

      @tanstack/history

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

      @tanstack/nitro-v2-vite-plugin

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

      @tanstack/react-router

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

      @tanstack/react-router-devtools

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

      @tanstack/react-router-ssr-query

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

      @tanstack/react-start

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

      @tanstack/react-start-client

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

      @tanstack/react-start-rsc

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

      @tanstack/react-start-server

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

      @tanstack/router-cli

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

      @tanstack/router-core

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

      @tanstack/router-devtools

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

      @tanstack/router-devtools-core

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

      @tanstack/router-generator

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

      @tanstack/router-plugin

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

      @tanstack/router-ssr-query-core

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

      @tanstack/router-utils

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

      @tanstack/router-vite-plugin

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

      @tanstack/solid-router

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

      @tanstack/solid-router-devtools

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

      @tanstack/solid-router-ssr-query

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

      @tanstack/solid-start

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

      @tanstack/solid-start-client

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

      @tanstack/solid-start-server

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

      @tanstack/start-client-core

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

      @tanstack/start-fn-stubs

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

      @tanstack/start-plugin-core

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

      @tanstack/start-server-core

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

      @tanstack/start-static-server-functions

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

      @tanstack/start-storage-context

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

      @tanstack/valibot-adapter

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

      @tanstack/virtual-file-routes

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

      @tanstack/vue-router

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

      @tanstack/vue-router-devtools

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

      @tanstack/vue-router-ssr-query

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

      @tanstack/vue-start

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

      @tanstack/vue-start-client

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

      @tanstack/vue-start-server

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

      @tanstack/zod-adapter

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

      commit: c6c33e2

    7. Merging this PR will regress 1 benchmark

      :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 improved benchmark ❌ 1 regressed benchmark ✅ 189 untouched benchmarks ⏩ 3 skipped benchmarks1

      Warning

      Please fix the performance issues or acknowledge them on CodSpeed.

      Performance Changes

      ModeBenchmarkBASEHEADEfficiency
      ❌Simulationhydrate restored route state and mixed Links (react)213.2 ms248.4 ms-14.18%
      ⚡Memorymem server streaming-peak chunked (react)642.3 KB349.8 KB+83.63%

      Tip

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


      Comparing codex/direct-compiler-ast (c6c33e2) with codex/fuse-clone-provenance (080a540) 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. ↩

    8. Notes for when this is recut on top of #8504 (now on Yuku 0.19.0), from a review of Yuku's APIs:

      • Other compiler-owned snippets that fit builders, beyond server functions:
        • react-start-rsc/src/plugin/rscCssTransform.ts: the { __tanstackStartRscCss: null } options object and the <>{null}{null}</> fragment, which are parsed then patched behind runtime guards.
        • router-plugin/src/core/code-splitter/compilers.ts: the console.warn(...) statement. console is a global, so it needs linkGeneratedReference(node, 'console').
        • start-plugin-core/src/start-compiler/handleCreateServerFn.ts: the parseExpression(functionName) identifier.
        • start-plugin-core/src/hydrate-when-transform.ts: parseExpression(preloadName) and the <Component {...props} /> child.
      • Keep template parsing where builders would be 3–10× longer: HMR blocks, the provider's extracted handler, import-protection rewrite.ts, Hydrate lazy imports.
      • Every builder identifier that refers to a source or import binding must go through linkGeneratedReference, or removeUnusedBindings prunes its import.
      • Yuku 0.19's generate() prints any single node, so the builder snapshot tests no longer need to wrap nodes in a Program. generateModule now accepts a Node.
      • b.Property returns ObjectProperty | BindingProperty and b.Literal the whole Literal union, which is why this PR writes ObjectProperty and Directive records by hand. We may ask upstream for precise builders.
      • parseStatements('') now returns [] without parsing, so the provider-directives call no longer costs an analyze when nothing is missing.

      Written with Claude Code (AI-assisted).

Sign in to join this conversation.