refactor(compiler)!: replace Babel with a Yuku-based compiler core for Router and Start #8817
main fromcompiler-rewrite/yuku·opened Includes the oracle test-suite branch
compiler-tests/baseline. That branch adds the oracle (packages/compiler-test-utils) and pins main's bugs as.fails. This PR replaces the compilers and turns the pins green.
Summary#
Every TanStack build-time compiler now runs on one shared core built on Yuku. That covers route code splitting and route HMR (router-plugin), all of Start's transforms (server functions, environment separation, <Hydrate>, RSC CSS, import protection) and the route generator. Babel, babel-dead-code-elimination and the Prettier hot path are gone.
On main, Babel took ~90% of compiler time. On 333- and 1,485-route React and Solid apps, builds are 2.1–4.5× faster and dev cold start is 2.0–4.9× faster. Start builds also end with 3–10× less heap.
Each module gets one plan per environment and config. Router-only apps parse a module once per environment; under Start, the raw read that cross-module summaries need adds one parse. Outputs no longer depend on transform or request order, and source maps are exact. The oracle's known-bug pins drop from 874 to 77 (36 keep main's behaviour on purpose, 31 are accepted or known limits, and the table below lists them all), and 27 open issues are fixed.
Server code: the guarantee is about the primitives: server functions and Start builders, import protection, .server files and markers, and the route options a client build removes. Each use of a Start builder or factory is either compiled or fails the client build at that use, so a shape the compiler can't follow doesn't ship silently. What this doesn't cover is listed under Behaviour changes.
Parts of this PR have landed on main as separate PRs (#8849, #8851, #8852, #8853, #8855, #8856, #8857, #8860, #8861 and the visible() fix #8653); this branch is merged with them, and their changes aren't described again here.
Architecture#
Full map: packages/router-utils/src/compiler/README.md.
- Analysis → plan → emit. Each (env, module, config, text) gets one analysis and one plan. The plan emits the env module plus derived modules (
?tsr-split=…,?tss-hydrate=…,?tss-serverfn-split,?tss-serverfn-handler) and facts (import edges, server-fn registry, diagnostics, dependencies). - Planners are the jobs. Each one adds edits and roots to the shared plan, in a fixed order:
start-env → hydrate → rsc-css → router → import-edges. APIs are recognised by binding, through an abstract value domain. Cross-module summaries come from raw text, never from the bundler pipeline; the route tree's imports ofRouteare answered from the route registry instead of a read of every route file. The JavaScript of.mdx,.vue,.svelte,.astroand.markomodules gets a late pass with import protection andstart-env, in place. On Rsbuild, a Vue SFC's script block is a module of its own under vue-loader's inline match resource (x.vue.js?vue&type=script…); a Vue-only rule runs the late pass on it, once per module. - Emit builds a rewrite tree over the original source ranges, so user code is never re-printed.
OutputBuilderwrites VLQ maps directly and composes them with input maps. - Reachability = splitting = dead-code removal, at cluster granularity. Code is removed only when our own edits orphaned it, so user side effects and unread imports stay. One mutation model (who writes each binding, and when) decides what may move. If a split does not settle within its re-planning bound, the route stays unsplit and a warning is emitted.
- Lazy server-fn handlers (when SSR is the provider). The handlers, and what only they reach, move to
?tss-serverfn-handler, which loads on the first call. The defining module runs once. - Builder escapes.
start-envtracks each Start builder or factory through bindings, re-exports, namespaces and factories. A use it can't follow is a compile error at that use: a client build fails before it emits, and in dev the module fails (overlay). There is no separate client graph check. - Verifier (
TSR_COMPILER_VERIFY=1, on in all tests). Every output is re-parsed and checked: no assignment to an import, glue imports resolve, each effect is emitted once, extracted outputs make no eager env-module reads, and extracted modules don't import each other in a cycle. - Caching and hosts. Caching is a plan cache, a dependency ledger and one
invalidate(); no Yuku objects are retained. We own the hosts: a native Vite plugin, a Rspack/webpack loader, and Start Rsbuild loaders (withbuildInforeplay for the persistent cache). Start's Vite and Rsbuild hosts share one bundler-free Start session; hosts keep only bundler wiring. On Rsbuild, the core's invalidation alone decides which dependents are stale: the loader registers no fingerprint paths as file dependencies, and stale dependents join the compilation through a synthesized file change. unplugin remains only for the generator and esbuild.
Performance#
Measured with benchmarks/compiler-perf at b7a8d45b2b against main da2adec76d. Both checkouts run at once on mirrored core sets, swapped per round and per cell, over 4 paired rounds (cut from 6, since main takes 45 minutes per round). Each round is 1 warmup + 1 run, 10 edits per HMR kind and 1 memory run. Values are medians, times are in ms and heap in MB. Large = 1,485 route files. Everything in this section was measured at b7a8d45b2b unless it names another commit, and these tables weren't re-measured at the final head. What moved since is under Losses and in the route-tree line below.
| large app | build | dev cold → hydrated | compile-all | HMR route edit | dev heap after GC |
|---|---|---|---|---|---|
| react-start Vite | 31,193 → 9,316 | 25,577 → 7,907 | 31,528 → 8,945 | 64.8 → 41.5 | 703 → 211 |
| react-start Rsbuild ¹ | 27,443 → 6,132 | 32,138 → 6,554 | – | 1,814 → 1,452 (n.s.) | 730 → 228 |
| react-router Vite | 11,789 → 3,378 | 11,835 → 3,239 | 27,084 → 5,468 | 53.8 → 31.6 | 103 → 92.0 (n.s.) |
| solid-start Vite | 44,295 → 20,600 | 31,778 → 10,935 | 44,240 → 19,701 | – ² | 618 → 210 ² |
| solid-router Vite | 17,813 → 8,539 | 14,723 → 4,645 | 41,482 → 15,770 | 875 (full reload) → 19.8 | 92.5 → 92.8 (n.s.) |
n.s. = the 95% CI includes 0.
¹ This PR's second round hit the harness's dev port race, so a redo round was added: build has 5 rounds, dev has 4.
² On main, this HMR run aborted in all 4 rounds (DOM never showed probe-component-…), which ends the run before any HMR result or memory value, so there's no HMR comparison. This PR had no abort. Heap and peak RSS come from a separate memory-only run of 3 rounds.
- tanstack.com (
598befed, offline, fresh clones,b7a8d45b2bvs main, 6 paired rounds):- Build: 19.6 → 12.9 s (−34%).
- Peak RSS: 3,820 → 3,090 MB (−19%).
- Dev cold → hydrated: 29.5 → 24.7 s (−16%).
- First visit of 15 routes (12.9 → 12.7 s), route edit (209 → 214 ms), shared-module edit (156 ms both) and server-fn edit (517 → 550 ms): each CI includes 0.
- It builds in all rounds. Warnings match the branch before the shape guarantee.
- Route rename (20 cycles, medians until the route is usable): Vite 2,952 → 724 ms, Rsbuild 4,963 → 867 ms. An open page on Rsbuild doesn't learn the new route, on either side.
- Rsbuild shared-module edit (a comment in a module with 373 importers, react-start medium, 6 rounds): the edit builds 1 + 1 modules, like main (about 265 ms). The branch before this fix built 853 + 869, and its medians fall from 641–759 ms to 208–255 ms per round. A warm start on the persistent cache is at parity with main (+25 ± 46 ms; +146 ms against the branch before this fix). A cold start is 1.9 s, vs 7.6 s on main.
- Rsbuild kept-binding HMR (
7da8433dc0, Start kept-binding apps, 3 paired rounds): hot-update latency is within the A/A spread for every edit kind. An edit of the kept binding shows in 248 ms (medium) / 1,293 ms (large), with no reload; before, it never showed. A component edit of a chunk that reads a kept binding sends +250 B (its registration); every other hot update is byte-identical. - Corpus (
064d29003a, 129 apps, medians of per-app Δ): build −12.1%, dev ready −18.8%, first render −10.5%, peak RSS −1.7%. - 13 large apps against main (
774eba05a4): builds are 2–26% faster in 9 and at parity in 3. kroma (barrel-heavy) builds 2.6% faster. - 14 large apps (against the branch before the shape guarantee,
e536af167a, own toolchains, 3 paired rounds): 0 new build failures, 0 new warnings, 0 server canaries in client JS. Client JS is unchanged in 13. redpanda is +79 B of 59 MB, with renamed chunks; that's unexplained, and looks like Rspack's id renumbering. tamery's comparison may be partial, because 3 npm copies of Start stay beside the override on both sides. - Import protection with
allowImport(real builds againsteb12efe304, 8 paired rounds): a build with an allowed import is 182 ms faster on Vite and 522 ms on Rsbuild. Clean builds, a dead 200-module denied graph and a failing live edge move by −26 to +46 ms. A dead re-export of a 400-module denied graph failed the build before and now builds. - Route tree answered from the registry (react-start large, vs
b7a8d45b2b): 1,490 raw builds per cold run are gone. In process, whole-app compile is −12 to −13%. In real bundlers, dev-compile peak RSS is −13% [−19, −6]; build (−3.3% [−11, 5]) and cold start (−1.3% [−4.7, 2.3]) have CIs that include 0. - Losses:
- Per-module compile since
b7a8d45b2b: +1.8 to +3.2% (react client +2.2, react SSR +1.8, solid client +2.3, solid SSR +3.2; micro-bench, 8 paired rounds at76ddc5e13e, identical output). The follow-up rounds through5bc674ea80added no measurable cost: againsteb12efe304, 6 cells over 8 paired rounds, every CI includes 0, and output hashes are identical. This round's lanes, each against its base over 6–12 paired rounds with identical output hashes: every CI includes 0 except react-start client +0.89% [0.04, 1.75] atf7664a8e8b(a separate run: −0.32% [−1.37, 0.73]) and solid-start client −1.47% [−2.58, −0.20] at3ee403ebeb. The<Hydrate>/kit/import-protection lane (758377e4d2→fbf9a67e59, 12 rounds) is 0.7–2.4% faster on Start's four cells (three CIs exclude 0), and +0.60% [−0.14, 1.35] / +1.32% [0.09, 2.55] on react-router client / SSR, which run no Start code. There's no micro-bench against main, because it needs an export main lacks. - Rsbuild large build peak RSS since
b7a8d45b2b: +15.6% [5.7, 16.7], 1,704 → 1,970 MB over 12 pairs atfa6a9906ed. Not retained, and not fixed. The excess is uncollected JS garbage at the end of the build (heap after GC −0.6%): without the route tree's 1,490 parses, V8's third mark-compact comes later and the build ends before the next one.b7a8d45b2blands in the same mode in 4 of 12 rounds, and with--max-old-space-size=640both sides peak at about 1,430–1,470 MB in the same wall time. Other cells are within noise. - solid-start/ssr at Yuku 0.27.0: +1.76% per module [0.77, 2.75], +1.24% [0.23, 2.25] on a 16-round rerun, with identical output. The iteration median and min have CIs that include 0, as do the other cells. Probably Yuku, since the only compile-path change on our side is a removed guard, but it wasn't isolated.
- The copy rule (see Behaviour changes): tanstack.com initial JS +25 B raw and one new warning; the 18 scenarios stayed byte-identical. They did so again at
60703bbcb8, and the Yuku bump changes 0 bytes. - Build peak RSS: solid-router large +2.4% (+25 MB, CI [0.1, 4.0]%); kroma +3.8% (+64 MB,
774eba05a4); tanstack.com's process tree +110 MB [21, 140] (+3.2%,758377e4d2→fbf9a67e59, 6 rounds; its build wall time, dev and HMR medians moved by at most 0.1 s). - Vue on Rsbuild (
db3211b2f1,rsbuild buildwith 200 generated<script setup lang="ts">SFCs, 8 rounds): compiling the script block costs about 1–2 ms per SFC, and 4.5 ± 1.4 ms per SFC with a server fn. Before, those blocks weren't compiled and their server code leaked. - The shape guarantee (
b7a8d45b2bvse536af167a, 6 paired rounds over 11 cells): +3.7–5.2 µs per module (+1.3–1.9% compile CPU) and +0.1–0.9% dev heap after GC (+0.1–1 MB). Pooled over the cells, build, cold start, compile-all and HMR all have CIs that include 0. tanstack.com's cold start is about +0.2 s of 24 s. - Rsbuild minimal client: +1 / +3 B gzip (raw −22 B; accepted).
- Server bytes: react-start.rsbuild.full is +605 B raw / +79 B gzip against main (summed per server directory). See below for the others.
- CodSpeed: memory on client navigation,
unique-location-churn(Vue) +3.1 KB,mount-unmount(Solid) +4.1 KB andnavigation-churn(Solid) +6.8 KB;interrupted-navigations(Vue) is −4.7 KB; 190 are untouched. CodSpeed notes that 2 of the changed benchmarks ran on different hardware for base and head. - Rsbuild dev: +29–39 ms per hot update (save → DOM, +11–14% on react-start medium), the cost of putting the original file text back into source maps (see Behaviour changes). Filed upstream as rspack#16348.
- Per-module compile since
- e18e framework tracker (their harness and starter on 2 CPUs, 12 paired rounds,
b7a8d45b2bvs main, 0 errors): dev server startup 1,460 → 1,305 ms (−10.6%), cold build 1,546 → 1,325 ms (−14.3%), warm build 1,403 → 1,224 ms (−12.8%). An estimate atda12a6f6ba, with smaller gains of −9.7 / −11.5 / −11.0%, put TanStack Start from #5 to #4 in cold builds and to #3 in warm builds, and left it at #5 in dev startup. The ranks weren't recomputed. The build margins were ~2%, smaller than the tracker's run-to-run spread.
All 11 cells, HMR, Vue, memory, bytes
Medium = 333 route files. Δ CIs are 95% t intervals of the paired log ratios.
| cell | build | dev listen | dev cold → hydrated | compile-all | dev heap after GC | build peak RSS |
|---|---|---|---|---|---|---|
| react-start Vite medium | 6,898 → 1,921 | 745 → 316 | 6,393 → 2,923 | 7,625 → 2,287 | 212 → 91.6 | 1,041 → 749 |
| react-start Vite large | 31,193 → 9,316 | 1,572 → 452 | 25,577 → 7,907 | 31,528 → 8,945 | 703 → 211 | 2,335 → 1,251 |
| react-start Rsbuild medium | 6,746 → 1,894 | 203 → 169 | 7,727 → 2,115 | – | 217 → 98.3 | 971 → 742 |
| react-start Rsbuild large | 27,443 → 6,132 | 210 → 158 | 32,138 → 6,554 | – | 730 → 228 | 2,634 → 1,685 |
| react-start-deps Vite medium ³ | 7,397 → 2,204 | 756 → 218 | 7,056 → 3,442 | 8,423 → 2,602 | 234 → 110 | 1,155 → 840 |
| react-router Vite medium | 2,944 → 740 | 645 → 181 | 3,646 → 1,134 | 6,886 → 1,480 | 63.8 → 48.7 | 630 → 435 |
| react-router Vite large | 11,789 → 3,378 | 1,391 → 284 | 11,835 → 3,239 | 27,084 → 5,468 | 103 → 92.0 | 1,113 → 746 |
| solid-start Vite medium | 9,913 → 4,718 | 771 → 261 | 7,770 → 3,482 | 11,222 → 4,874 | 191 → 94.6 | 1,317 → 974 |
| solid-start Vite large | 44,295 → 20,600 | 1,607 → 367 | 31,778 → 10,935 | 44,240 → 19,701 | 618 → 210 ² | 2,761 → 2,140 ² |
| solid-router Vite medium | 4,496 → 2,104 | 633 → 256 | 4,099 → 1,741 | 10,436 → 4,453 | 63.0 → 55.7 | 688 → 600 |
| solid-router Vite large | 17,813 → 8,539 | 1,521 → 347 | 14,723 → 4,645 | 41,482 → 15,770 | 92.5 → 92.8 | 1,060 → 1,085 |
³ react-start plus a generated dependency graph and tanstack.com's manualChunks. Dev SSR fails on both sides here because of a ?url wasm asset in the harness, so <Hydrate> HMR is not measured.
- Speed: every cell is significantly faster. Build −52…−78%, listen −17…−80%, cold start −51…−80%, compile-all −56…−80%.
- HMR (p50, cells whose CI excludes 0):
- Route component −15…−98%, loader −15…−51%, server fn −35…−79%.
<Hydrate>is −9…−42% on Vite and −21 / −45% on Rsbuild.- Shared-module edits are −32 / −54% on Rsbuild.
- No cell is significantly slower. Rsbuild route and loader edits (−17…−30%) have CIs that include 0, as do react-start large loader edits. solid-start large has no comparison ².
- Memory: dev heap after GC is lower except on react-router large and solid-router large (both n.s.). Build heap after GC is 3–10× lower on Start and 1.1–1.6× lower on Router. Peak RSS is lower except for the loss above. 100 edit + revert cycles show no growth (
eedc638e42). - 500-cycle soak (
18ef570edc, KB/cycle, PR vs main): react-start Vite −0.7 vs 11.2, react-router Vite 2.3 vs 6.3, react-start Rsbuild 20.9. The soak found five records that grew with deleted files; all are fixed and tested. The remaining growth is upstream (vite#23907, rsbuild#8736). - #8614: import protection in dev adds +2.4 MB of heap, down from +321 MB.
- #8794: in Start + Nitro builds, heap is 64.3 MB here, vs 506.5 MB on main and 98.7 MB on main with the issue's fix (
fdc48254c8). - Vue (1 paired round, medium; Vue Start / Vue Router): build 8,665 → 3,917 / 4,162 → 1,588 ms, cold start 10,692 → 3,073 / 5,017 → 1,349 ms. Every HMR edit applies in place, whereas main full-reloads Vue Router route edits.
- Other builds (
eedc638e42): webpack build −38%, RSC build −74%. - Generator without Prettier (
498ac9be17): 715 → 94 ms. The react-start build floor drops from 1,629 to 779 ms. - Client bytes (18 scenarios):
- 12 are byte-identical.
*.fullscenarios are −38…−52 B gzip, thanks to shorter server-fn ids. They include a scenario edit (−6 B raw): the old*-start.fullsource stored factories in an array, which a client build now refuses.- Rsbuild minimal is larger because Rspack renumbers module ids once our loader request changes.
- react-start.full brotli +86 B is q11 noise.
- Server bytes (
.js/.mjssummed per server directory, gzip −9; these totals don't matchserver.mjs's own, which can't measure main): Vite scenarios are −450…+4 B raw and −48…+99 B gzip. react-start.rsbuild.minimal is +23 raw / −10 gzip. react-start.rsbuild.full is +605 raw / +79 gzip:- the resolver imports the defining module, which makes
__roota second concatenation root, so router modules shared with the route tree stay unhoisted; - lazy handlers add their per-file glue;
- one named cache group merges the server-fn provider chunks into the router chunk, recovering the extra chunk's overhead (−94 raw / −248 gzip; no Rspack version requirement).
- the resolver imports the defining module, which makes
- SSR cold start (a server fn imports a 1.5 MB SDK that
GET /never calls; main / eager handlers / this PR): Vite ~88 / ~145 / ~88 ms, Rsbuild ~57 / ~122 / ~57 ms.
Testing#
The oracle (packages/compiler-test-utils/oracle) drives real bundlers, dev servers and browsers through public APIs only. Main's bugs are pinned as .fails.
baseline (main's compilers, 80d1890bed) | this branch (deb31957e1) | |
|---|---|---|
| tests | 3,594 | 6,070 |
known-bug pins (.fails) | 874 | 77 |
| non-pin failures | 0 | 0 |
- Oracle: 6,070 tests and 77 pins at
deb31957e1. Each lane of this round ran it in normal and pins mode against its base: 0 status changes of existing tests, apart from 12 Rsbuild kept-binding pins that now pass as ordinary tests and 4 new pins (an ordinary module importing a binding from a route file, Follow-ups). The<Hydrate>/kit/import-protection lane (fbf9a67e59, against758377e4d2) adds 50 tests and removes 4 (the.inputValidator()case and a renamed test). - Other gates, per lane on its own head: unit, noncompiler, types, eslint and integration pass. Fuzz (20,000 cases per lane): 0 crashes, unexplained cases identical to the base, and per-seed changes only in the timing class (10, in the fix list; 0 elsewhere once the generator writes
.validator()). Client bytes are identical in all 18 scenarios. The last full e2e runs (145 projects):fbf9a67e59's tree, 5,007 passed, 0 failed, 0 flaky;deb31957e1, 5,118 passed and one failure, the Rsbuild error-overlay spec's console allow-list, which now names Start's located parse error and passes. The last two lanes (17e475671e,9fc07dc514) ran unit, integration, types and eslint of the packages they touch, and the WorkOS example's build. - Known flakes:
- Watchpack double compile: a save that lands in the millisecond its compile starts compiles twice, about 1 save in 10 on a long-lived Rsbuild server. Plain Rsbuild does it too, and the output is the same. The test now asserts which modules are built instead of counting builds, which tolerates it.
- Solid
serialization-adaptersstream: the router's$_TSR.e()deletes$_TSRbefore Solid's last script reads it. It fails on main too (main 4/20,b7a8d45b2b5/20). It isn't a compiler bug and is out of scope for this PR. route-edits-after-tree-rebuild(Vite): fails under heavy CPU load, onb7a8d45b2band on the base before the shape guarantee. A page requests a renamed-away route and gets a 404. Cause not determined, and not checked on main.- kroma dev (large-app runs):
ERR_INSUFFICIENT_RESOURCESin 8 of 36 runs on each side (eb12efe304and this branch, one side at a time), with the same shape. Not a regression. <Hydrate>page tests: the harness'ssettled()could return before avisible()boundary's IntersectionObserver fired, so the test read no chunk request (CI's empty-chunks failure). It now waits for the observer, idle time and requests in flight. Under load, 14 of 405 page runs requested the chunk aftersettled()before, 0 of 420 after. Still open: under heavy load, page runs time out while loading, on both sides (whole page suite on 2 CPUs, 4 paired rounds: 5 timeouts before the harness fix, 10 after, in the same tests).- vue-router
routeContext(CI ate27395a033): the test took 1,027 ms against Testing Library's 1,000 msfindByTextdefault (it sleeps 3 × 150 ms first). It passed 20/20 locally on this branch and on main; not fixed.
- CI out of memory:
start-plugin-core's integration worker died at its 2 GB limit because the test harness retained builds through async contexts. The harness now releases them, with no limit raised and no project split: peak 1,636.2 MB after GC ata5ca5977da, and 1,758.2 MB at17e475671e(1 worker,--max-old-space-size=2048, heap limit 2,144 MB) after this round's Rsbuild dev-server files (Follow-ups). The main remainder is a Vite 8 / Rolldown retention: a plugin passed to Vite 8 is never released. One CLI build, one dev server and watch mode don't accumulate; a long-lived process running many programmatic Vite builds leaks about 5.5 MB per build at 338 routes. Node's compile cache now lives in each test run's directory and is removed with it (it had reached 14 GB in/tmp). - CI at
eb1a7841bb: all 32 checks pass, including the Test job and the Windows x64, macOS arm64, Linux arm64 and Linux x64 musl platform jobs. Earlier failures this round were the WorkOS example (@workos/authkit-tanstack-react-start0.5.0 called the removed.inputValidator(); the example now uses^0.12.0, see Behaviour changes), the vue-router flake above, and test-only fixes on Windows and macOS (symlink target spelling, the stats registry count, the run directory's teardown).
Beyond the oracle:
Real-app corpus: 190 public repos, each built and dev-tested with npm main and with this PR, in a network-restricted sandbox.
Start app corpus for the shape rules: 250 cloned app roots and 3,677 sampled roots, read for false refusals. It caught a regression in the last round, now fixed.
Shape harness: 340 builder, import-protection and route-option shapes, in 922 result rows at
b7a8d45b2b, each a real run on Vite, Rsbuild, RSC or a dev server, with the server import named plainly or.server. On the 133 first-round rows (Vite, plain name), main has 45 ok, 80 silent leaks and 8 build errors. This PR has 82 ok (2 of them with a warning), 43 build errors and 8 leaks (2 with a warning). Each remaining leak has a ruling; the groups are under Behaviour changes below.Leak check: a canary in the server-only code of 124 in-repo Start apps. At
b7a8d45b2b, 139 builds, 138 built (clerk-basicfails on main too): 0 of 1,318 canaries in client JS, and 0 in source maps only.Differential fuzzers for compiler output (run against the untransformed source), the route generator, and HMR edit sequences on 5 frameworks.
Internal verifier, on in all tests.
Coverage-targeted tests. Each fix round below also went through five read-only reviewers, whose regressions were fixed test-first.
Five independent coherence reviews, each followed by a consolidation pass, plus two review waves on architecture, useless work (profiled) and dead code. They led to staging the placement and plan code, one router planner, one Start session for both Start hosts, dead code removed, and ~30 ms less main-thread CPU per Rsbuild dev edit. The last wave also led to the
vite build --watchand server-fn registry fixes. Each pass kept client bytes identical and compile time at parity or better.External review: an agent with no project context reviewed
37e941dfe6by reading the code. Three fact-check lanes then ran every claim against the head and main, with pinned tests.- Confirmed and fixed, with regression tests: the prefetch race that leaked a handler, pattern imports bypassing import protection, plan-cache concurrency, a re-exported route factory, unparsable route files, placement shapes, stale importers of route exports,
vite build --watch, and the Rsbuild dev fan-out. - False or unreachable in real use: the SSR
hot.accept()claim, the derived id of an unparsable file, and memoised facts errors. Cached resolutions are false for tsconfigpathsand by design for the rest.
- Confirmed and fixed, with regression tests: the prefetch race that leaked a handler, pattern imports bypassing import protection, plan-cache concurrency, a re-exported route factory, unparsable route files, placement shapes, stale importers of route exports,
Second external review of
b7a8d45b2b, fact-checked against that commit and main by two lanes, with pinned tests.- Confirmed and fixed, with regression tests:
- module state and identity behind copied exports, in production builds on every bundler (main shared one instance; the shapes are absent from 160 real apps);
- a throwing resolver killing the Vite dev server (main answers a 500);
package.jsonimports/exportsedits leaving a stale resolution, and server code on the dev client until a restart;- file-event storms (up to 18 s stalls on a 3,000-module app; now at parity with main);
- enum member effects moving out of evaluation order;
- import specifiers such as
constructoror__proto__findingObject.prototypein a table and failing the build; - a plugin giving a route and its chunk different text, now the
input-text-differswarning.
- False, or not a regression:
buildItems,regionReadsandsetImmediateper import aren't pits. Exhausted fallback rounds are unreachable with the real planners. Lazy handlers behave as on main. Superlinear terms exist only in extreme shapes: a real 6,898-line route compiles in 74 ms, and builds beat main up to 50,000 lines.
- Confirmed and fixed, with regression tests:
Later rounds also fixed:
- an Rsbuild dev panic when a rebuild revoked a module later in the same batch;
- an Rsbuild persistent cache restoring another compiler version's outputs;
- routes merged with a type namespace not splitting (one case leaked);
- Rsbuild's SSR layer acting as server-fn provider under RSC;
- an RSC CSS placement regression, which e2e caught at
fa6a9906edand never shipped in a release; - a top-level
createIsomorphicFn().server(f)()dropping other statements of its module, which then threw at load (main works); - a statement followed by a
/* @__PURE__ */call on the same line, which moved the annotation with the statement and dropped the statements after it on Vite 7/8, Rspack and webpack. An annotation or license comment that ends its line (a; /* @__PURE__ */thenmk()on the next line, also// @__PURE__and#__NO_SIDE_EFFECTS__) now stays with the code after it too; before, a following statement was dropped on Vite 7/8 and webpack; - a removal that left the next statement starting right after other code: a statement starting with
(,[or a regex was glued to it (aTypeErrorat load, or a build that failed); - state read at load moving into split code: a callback a top-level call runs (
const labels = ['v'].map((k) => prefix + k), withbeforeLoadwritingprefix) ran when the chunk loaded and saw the later value. "Runs at load" now has one definition for every placement rule, and that code stays in the route module; - the kept-declaration warning with several bindings (it said "changes they");
- an Rsbuild rebuild scanning the whole module graph before each module it rebuilt (a warm restart rebuilding hundreds of modules spent seconds there); it now asks the graph (100 rebuilds of 1,000 modules: 1,000 visits instead of 100,000);
- the generator replacing a symlinked route file or
routeTree.gen.tswith a regular file; it writes through the link; - Rsbuild on Windows treating a
package.jsonedit as an ordinary file change (native paths), so the resolutions it redirects stayed stale; - Rsbuild dev losing the warnings of a compilation replaced before Rsbuild printed it (a cold start's first client compile, when the generator writes the route tree): import protection's
mock-mode reports and the compiler's warnings are now printed with the next one; - an HMR rename of
compin a nestedvar { comp = 1 } = o, and of an annotatedconst comp: FCin dev, leaving a dangling reference and a blank page; - import protection: awaiting a mock froze the tab or the server; on Vite, a denied file importing a package with only
nodeexports failed withErrored while resolvinginstead of the denial; a dead re-export of a denied module was reported when its graph had more than 256 modules or it imported a builtin, the framework's server runtime or asideEffects: falsepackage; and, with an allowed import,build --watchwrote no client andrsbuild buildnever exited under RSC. - The edit order is now named bands instead of numeric gaps, with 72,460 output hashes identical.
Every PR bug these found is fixed, with a regression test, except the open items under Follow-ups and a few rare shapes from the last review rounds, which aren't listed here. The fuzz differences that remain are pre-existing on main or upstream.
Results
Corpus (b25984c166 vs npm main):
- Builds: 189/190 build on both. The 1 PR-only failure was a type-only import re-emitted as a value import, fixed in
390ca815c3. - Bytes: client JS 405.01 → 404.72 MB, initial JS 101.42 → 96.92 MB.
- Leaks: 0 server-only canaries in client JS on either side.
- Dev: 158 equal, 18 PR better, 4 PR worse, 6 mixed, 4 both fail.
- The 4 worse: the type import, a global-boundary reload (main's behaviour), a pre-existing Vite optimizer race, and noise.
- Route-edit HMR median: 159 → 105 ms (71 pairs).
- Bugs it found, all fixed:
- effectful declarations only split code reads stayed eager (+110 KB initial);
- extracted-export TDZ cycle;
- server-only deps kept by function-local chains;
- lost ASI before
(/[; - handlers' server-only imports loaded at boot (500s; fixed by lazy handlers);
- Solid Start fix edit not shown after an error.
- Main sometimes emits fewer chunks; that happens only with two
@babel/traversecopies, which break main's DCE.
Leak check against main (139 builds per side, 5ff36a1816): 0 leaks here. Main leaks in mock mode; that case is pinned.
Fuzzers:
- Compiler (110,000 cases):
- 0 env-separation differences.
- 0 PR reference errors, wrong values or duplicated effects.
- 1 TDZ fixed; unread imports are now kept, as on main.
- Each later fix round re-ran 20,000 new cases.
- Generator (51,000 trees, each generated by main and four times by the PR):
- 0 crashes or nondeterministic outputs.
- 2 cases fixed.
- HMR (1,040 sequences):
- 4 bugs fixed.
- 322/1,540 steps full-reload, vs 740/1,436 on main.
- The rest are pre-existing or upstream (solid-refresh#91, #92).
Coverage: lines 91.1 → 91.5%, branch arms 79.2 → 80.2%. No bug found; 2 unused paths deleted.
Vite 6 / 7 (5ff36a1816): the 13 router-plugin e2e projects pass on Vite 6.0.15, 6.4.5 and 7.3.7. Split Solid and Vue routes update in place, where main full-reloads.
Remaining fail pins (77)#
| reason | # | expected behaviour still missing |
|---|---|---|
| Kept main's behaviour on purpose | 20 | Route CSS applies only once the route matches. This needs a per-route asset loader (follow-up). |
| 16 | A root route's error/not-found component loads lazily. Root routes are never split: splitting cost SSR CPU on error renders, and the chunk was preloaded anyway. | |
| Accepted (safe direction, R89) | 10 | An importer exempted by exclude/ignoreImporters that reaches a denied file only through a pattern import (import.meta.glob, template import(), webpackContext) gets the real module. It gets the mock: the file is judged at its own compile, which doesn't see these imports. |
| 5 | An importer outside srcDirectory/include gets the real module of an in-scope denied file it imports. It gets the mock, for the same reason. | |
| 1 | An importer outside the scope that reaches a denied file also outside it, only through a pattern, gets the real module. It gets the mock, for the same reason. | |
| Known limitation | 6 | A Vue <script setup> block that hands a Start builder or factory to its template is a compile error on the dev servers (Vite and Rsbuild) and in builds with Vue's devtools (Vite: features.prodDevtools, a true __VUE_PROD_DEVTOOLS__ define or NODE_ENV=development; Rsbuild: NODE_ENV=development): there compiler-sfc hands the block's bindings to the template, in JavaScript every import too. Hit by a JS block importing a builder or factory, and by any block whose local holds an open builder. No server code ships. The error names the binding at its declaration in the SFC, with the recipe: lang="ts", builders and middleware in a .ts module or a module-scope <script lang="ts">. A default production build inlines the template and builds. A fix must not need a special case for the plugin's output: skipping its generated object ships a template-attached handler (pinned). |
| 4 | On Rsbuild and webpack dev, an ordinary module importing a binding from a route file sees an edit of that binding. It keeps the first value until a reload: the route module self-accepts and the importer's text doesn't change. The route file's own split chunks do get the edit. | |
| Not covered, as on main | 5 | These forms on a client build are mocked and reported: a clean ?worker importing a denied file; new URL('./x.server.ts', import.meta.url); a marked .mdx/.vue with an asset query; a marked file that doesn't parse with an asset query; on Rsbuild, a plain webpackContext of a denied .json. They reach the client unreported. |
| Bundler limitation | 3 | On rspack/webpack/rsbuild without sideEffects, an exported component another route's chunk imports loads with that chunk. |
| 1 | On Rsbuild dev, a custom module type (.page as javascript/auto) importing a denied specifier is reported. Rspack rules select by resource. | |
| 1 | On Rsbuild build, an unused exported component with a boundary emits no async chunk. | |
| 1 | On Rsbuild dev, an edit of a linked package's exports that turns an import from plain into a builder strips the handler when the importer is edited in a later compilation. Rspack reports no event for that package.json, so the resolution stands until a file is added or removed. | |
| Upstream | 1 | On Rsbuild dev, adding a route's first server fn shows on the open page (rspack#16288). |
| 1 | On Vite, a split chunk reading a var declared again in a for-in/of head or a pattern gets its last value. The compiler's output is correct; Rolldown inlines the first value across modules. | |
| Not supported yet | 1 | In Vite bundledDev, a factory that becomes a server-fn builder keeps its handler. This needs the full-bundle API. |
| Accepted shape outcome | 1 | withBuilder(createIsomorphicFn().server(f)).client(g) keeps each implementation. .server() finished the value, so nothing refuses it and the module throws at load, as on main. No server code ships. |
Behaviour changes#
- Builds that now fail (client build, at the use, with a message saying what to write; in dev the module fails, with the overlay). Main shipped most of these silently:
- A builder or factory the compiler can't follow: passed to a function (
id(createServerFn()).handler(h)), stored in an object, array or class field, awaited, or a JSX prop. - A method read off a builder:
const h = createServerFn().handler,.call,.bind, or an unknown method such as.foo(). - A factory with control flow: an
ifwith tworeturns, or an async function, method or getter. Also aletbuilder reassigned with something else, a builder in a TSnamespace, and a project namespace object passed around when its module exports a builder. - A client-only
createIsomorphicFn().client(fn)orcreateMiddleware().client(fn)passed to other code: usecreateClientOnlyFn(fn). - A parameter passed directly as server code:
(fn) => createServerOnlyFn(fn),({ handler }) => createMiddleware().server(handler),.validator(param). - RSC:
renderServerComponentorcreateCompositeComponentoutside a server function. - A route factory call the planner doesn't own (not
export const Route = createFileRoute(path)(options)) that carriesserver,ssrorheaders. A route file whose factory comes from an app re-export also fails under Start (a warning elsewhere). - A module the compiler can't parse, if it's JavaScript or TypeScript in scope: Flow and Babel-only syntax included, and TypeScript that tsc rejects but SWC accepts (
let v!: T = x). CommonJS scripts and other files are left to the bundler. .inputValidator()(renamed to.validator()in #7566, removed from Start's runtime in #8694) is no longer recognised: the build fails at the call, saying to call.validator()or to update the dependency that calls it.- Newly compiled, so these no longer leak: a destructured namespace (
const { createServerFn } = Start),(0, createServerFn)(), a builder chosen by?:,??,||or&&, a factory with statements before its singlereturn,export * as ns, aletreassigned with a builder of the same kind, aconstmiddleware list, andcreateServerFn.call(thisArg, options).
- A builder or factory the compiler can't follow: passed to a function (
- Route options the compiler can't read build and warn: a spread, options from a call or an import, options written to after their declaration, and a computed key. What they hold isn't split or removed, so any server code in them ships to the client. The warning says what to write. A
server,ssrorheaderswritten next to a spread is still removed, and an edit of a route whose whole options can't be read reloads the page. Rsbuild dev doesn't print these warnings on warmbuildCacherebuilds. - A parameter only read inside server code (
(role) => createMiddleware().server(() => check(role))) gets one warning at its definition: what callers pass for it still ships to the client. - Unparsable route files fail cold runs:
tsr generateand builds reject, naming the file, the root route included. A dev server or watch session warns and keeps the last good route. routeTree.gen.tsformatting changes once. The file is printed in yourquoteStyle/semicolons.enableRouteTreeFormattingnow defaults tofalse(trueuses Prettier, loaded lazily). Custom templates are inserted as written.- Server-only server fns: a server fn that only server code calls, or that is only returned as data, is not HTTP-callable in production. Dev still answers it, with a warning.
serverFns.generateFunctionIdreceives main's handler name asfunctionName(greetUser_createServerFn_handler, with_nfor a repeated name; a non-ASCII character becomes_). A custom id must be one URL path segment: ASCII letters, digits,-,.,_,~and$, not.or... Otherwise the build fails, naming the function. Ids with%,:,@,+and the like, which worked on main through Node, now fail. Default ids are shorter.- A server fn an edit removes is an unknown id on the Vite dev server (
Invalid server function ID). Main answered a 500TypeError. vite build --watchof a Start app builds and rebuilds against each edit: the server builds after the client's first build, and a server fn the client stops importing is no longer HTTP-callable after the rebuild.- Server-fn handler modules run once, on the first call. A handler stays eager if it writes module state or its module uses top-level await.
<Hydrate>through the app's own re-exports (a barrel,export *, a namespace import) is split as when imported from Start. A renamed re-export, or one through a package, stays unsplit.- Kits that list Start under
dependencies(not peers) are bundled on the Vite server, like peer kits. Before, their server fns failed in Vite builds (not a server fn URL: undefined). - What runs at load (top-level code and the callbacks it passes to calls) has one definition, so code that reads state at load stays in the route module. Some components are kept that needn't be (React
memoorforwardRefwhose body reads a server fn, store or context;createClientOnlyFn(async () => fn())). Keeping one makes its code eager, on the server too, which can expose a browser-only top-level read to SSR. VuedefineComponent({ setup })is excluded. tanstack.com's 335 route files don't change. - Exported page components are split (
?tsr-split=export~Name), together with their augmentations. On one corpus app: −179 KB initial, +2.4 KB total. - Exported bindings of a route file: a chunk copies an export only when it and what it carries are functions and primitive constants that nothing writes or compares (
new,instanceof,===,.prototype). Everything else (a class, an object or array literal, a call result, a regex, an enum, a written binding) keeps one instance: the chunk imports the export's extracted module, in builds as in dev. Exports in a read cycle share one extracted module. A copied function has two instances (importers of the route file, and the chunk). A value with an identity that an extracted module and other split code both need stays in the route module, and the build reports it. - A plugin that changes a route's text for only some ids gets an
input-text-differswarning in every mode. It fires for any differing text, including a harmless plugin, and stays silent for a dev compile within 2 s of the file's save. The texts aren't forced to match. - Imports read only by moved code move with that code. Unused imports stay, as on main.
- Stays unsplit, with a warning: route callbacks that read
this(#8688), splits that never settle, and aRoutethat isn't one variable. A type namespace sharing a name with a route or its options doesn't count: that route splits. - React + Vite route HMR with exported values: a route file exporting a non-component value (e.g. a query options object) reloads on edit, as on main, so its importers see the edit.
- Route HMR after a render error reloads the page in dev, as on main. This applies to any boundary on Solid/Vue, and to the global boundary on React.
- Import protection:
- per-edge mocks export the target's names;
- build verdicts come after tree-shaking;
allowImport(info)decides,onViolation(info)reports (breaking).allowImportruns during the build, before the import is replaced by its mock, in dev and builds, once per import;truegives the real module from the first pass, with no report. It also sees imports tree-shaking removes later, and itsinfohas notraceorsnippet.onViolationruns after the build, for imports that survive tree-shaking and weren't allowed, and changes nothing. Returningfalsefrom it no longer allows the import: the import gets the normal outcome, and Start prints a message pointing toallowImport. On main,falsesilenced the report but mostly left the mock: in builds the client got the real module only for a Vite marker, and in dev only on Vite witherrorfor specifier and marker imports. A build runs each environment once: there's no rebuild pass, and Start no longer patches Vite'sbuilder.build. With RSC, a'use client'file allowed fromrscis the real module inssrtoo;- traces follow the bundler graph;
- a Start builder chain with pure arguments is no effect, and what a compile erases on one side (a handler and what only it reads) doesn't count there, so a dead re-export of a server-fn module is no longer reported;
- pattern imports of a denied file (
import.meta.glob, templateimport(),import.meta.webpackContext) serve its mock and report it, on Vite and Rsbuild. A build names each importer, and a dev server names the file. Rsbuild builds witherrornow fail on these, where main's Rsbuild and dev hosts mocked silently; - asset queries (
?raw,?url,?inline,?worker,?sharedworker) of a denied or marked file serve the mock, never its text, also through a pattern. On the client, a denied file is judged wherever it lives; - known incorrect rejections, accepted (safe direction: the mock, never server code): an exempt importer gets the real module of a denied file it imports plainly, but the mock when it reaches the file only through a pattern, and an importer outside the scope gets the mock of an in-scope denied file (the guide's "Limitations"). As on main, but now with a warning: in dev about the file, in a build once per file, naming its importers and the fix. The warning is not a violation and never fails a build. A dev server also reports a denied file it compiles with no importer (e.g. a
server.warmupglob).
- Source maps on webpack/Rspack/Rsbuild hold the original file text, so devtools show the file as written. Main showed the code splitter's output under the file's name.
- Vite +
@vitejs/plugin-react: an edit that makes a split chunk throw while it loads reloads the page (split components are refresh boundaries, which plugin-react makes self-import, and Vite reloads failures in a circular import). The fixing edit applies in place. - Start router options follow one rule on Vite and Rsbuild: client
addHmris always on. - Rsbuild/webpack dev, a split chunk reading a binding the route module keeps (an exported object, or a value the loader also reads): an edit of that binding now reaches the chunk. The chunk registers with its route through the framework's
/hmrentry, and the route module invalidates it and refreshes the route once. Solid loses component state on those edits. An ordinary module importing a binding from a route file stays stale (pinned, Follow-ups). - Diagnostics on Rsbuild, Rspack and webpack carry their position (
File: ./src/fns.ts:3:28,WARNING in ./src/routes/index.tsx 2:22) instead of:1:1or none. The router plugin's loader errors are namedTanStackRouterCompilerError. - Rsbuild:
- Vue SFCs (
@rsbuild/plugin-vue, or vue-loader throughtools.rspack): the script block (<script setup>or<script>) is now compiled; before, with the plugin's default inline match resource, no Start pass saw it, so server code shipped to the client and isomorphic fns ran their server side in the browser (dev and build). Without the inline match resource the late pass ran two or three times on the block and its server fns failed when called; it now runs once. - server-only routes are pruned from the client;
- manifests list only a route's own chunks;
- the persistent cache works, and its key holds the compiler packages, so an upgrade doesn't restore another compiler's outputs (a router-only app's cache doesn't have this key, as on main);
spa.enableddev serves the shell;server.compressis no longer forced;- the server env shares async chunks;
- RSC CSS HMR needs
@rspack/core≥ 2.2.9 (web-infra-dev/rspack#15865). Start's peer floors are nowvite≥ 8.1.0,@rsbuild/core^2.2.13 and@rspack/core≥ 2.2.9 (react-start-rsc); router-plugin keeps@rsbuild/core≥ 1.0.2 || ^2.0.0 (its Rsbuild integration tests pass on Rsbuild 1.7.6). rsbuild build --watchpicks up route files created while watching.- on Rspack 2.1.0–2.1.2, open tabs reload after a dev warm-cache restart (an Rspack bug fixed in 2.1.3).
- Vue SFCs (
- Solid Start server envs split like the client. Vue Start dev no longer reloads after dependency optimization.
- Requirements:
@babel/coreis no longer transitive, so declare it if a plugin needs it (e.g. React Compiler).- router-plugin's
unpluginstays at main's^3.5.0.
- Removed:
- Babel-typed experimental hooks: Start
compilerTransforms,serverFnProviderModuleDirectivesandStartCompilerPlugin; react-start-rsc/plugin/rscCssTransform, replaced byrsc: { loadCssExpression, providerDirective };- router-utils' Babel helpers (router-utils gains
/compiler); - router-generator's
format,inferFullPath,checkRouteFullPathUniquenessandwriteIfDifferent.onRouteTreeChangednow receives{ model };
- Babel-typed experimental hooks: Start
- New dev-only subpaths:
@tanstack/router-core/hmrand@tanstack/{react,solid,vue}-router/hmr. - Vue
<script setup>(known limitation): onvite dev, Rsbuild dev and in builds with Vue's devtools on, a block that hands a Start builder or factory to its template (a JavaScript block importing one, or any block whose local holds an open builder) is a compile error at that binding (createServerFn` is a TanStack Start builder or factory, and the code Vue generates for this component hands it to the template…). Use<script setup lang="ts">and keep builders in a.tsmodule or a module-scope<script lang="ts">. Default production builds are fine. Pinned. - Examples: the WorkOS example uses
@workos/authkit-tanstack-react-start^0.12.0(0.5.0 called.inputValidator()), with what that needed:@workos-inc/nodeas a dependency (the kit's peer), sign-in through a/api/auth/sign-inserver route (the kit's per-flow PKCE cookies), Start's CSRF middleware added beforeauthkitMiddleware()(a customrequestMiddlewarelist drops the default), andWORKOS_API_KEYoptional. - Not guaranteed, on purpose:
- Plain code the client also reads: a plain server-side call in a declaration the client reads, comments, and leaves read through other declarations aren't chased. What callers pass as a parameter ships. Write server code inside the primitives.
- Source maps: published maps hold your source. If you don't want to leak code, don't publish them.
- Virtual modules (known limitation): code manipulation in virtual modules isn't supported. A Vite build can hang on
virtual:modules that import each other, or on one with a server-only marker: the compiler reads a virtual module's raw text throughthis.load, which settles after the module's transforms, and a compile among them waits for that text. It has no pin and doesn't fail closed. - Dynamic loading of Start objects:
import(),require()andimport.meta.globneither fail nor warn. Keep builders statically analyzable. Import protection of denied files through patterns is separate and stays. - Other tools and APIs: modules other plugins generate or rewrite, Vite's worker build,
Route.update(), code-basedcreateRoute({ server }), which Start doesn't support, private package paths, and a file read on purpose as text (./fns.ts?raw) unless import protection denies it. - Import protection rules: they read names and what an in-scope importer writes. A
.serverfile behind a neutral module outside the scope stays reachable, as on main, and the forms in the "Not covered" pin row reach the client. - Two outcomes worse than main, kept by ruling:
import('…/server-only')inside a function the client keeps no longer fails the build (a top-level one still does), and an isomorphic.client(() => ({ handler: (f) => f }))followed byiso().handler(h)shipsh.
42 changesets. Minor bumps: router-utils, router-generator, router-plugin, router-core, start-plugin-core, react-start, solid-start, vue-start and react-start-rsc. Everything else gets a patch.
Follow-ups#
- Server fns sent to the client as data: add an explicit
createServerFn({ serializable: true }). - Fully lazy route CSS (#4396): needs a router-core per-route asset loader.
- Prettier: make it an optional peer.
- Rsbuild
__rootcache group: unblocked now that the Rspack panic (rspack#16289) is fixed. - Rsbuild dev source-map text: drop the post-hash
.mapfill once Rspack can fill it natively (rspack#16348). - Open issues to handle separately: the #8437 CLI half, #4462, #6331 (solid-refresh#91), #7827 and #6400.
- Docs: with RSC, a server-fn module's state exists once for server fns and once for server components.
- Bundle-size benchmark scenarios: the
solid-start.fullserver scenario renders its error page andvue-start.fullan empty shell, also on main. Code bytes stay valid, but response size and cold-start timing of those two measure a failed render. Fix them in a separate benchmark PR. - Rsbuild client manifest: main's
normalizeRspackClientBuildruns on every Rsbuild dev client compilation (~92 ms per edit, about a third of the busy main thread). It's unchanged here. - Known, open:
- Rsbuild/webpack dev, a module importing a binding from a route file (known limitation): the route module self-accepts and the importer's text doesn't change, so an edit of that binding doesn't reach it; it keeps the first value, with no error, until a reload. The route file's own split chunks get the edit. Vite is fine. Pinned (4 rows).
- tanstack.com dev crawl:
/ethoshangs in 6 of 12 runs here and 4 of 12 oneb12efe304, with no import-protection activity in those logs. Not checked on main. - Solid
serialization-adaptersstream: the race under Known flakes; on main too, out of scope. <Hydrate>page tests under load: page runs time out while loading, on both sides (Known flakes).- CI memory margin:
start-plugin-core's integration project on 1 worker peaks at about 1,760 MB after GC against its 2 GB limit (1,758.2 MB at17e475671e). The Rsbuild dev-server files added this round take 30–52 MB each.
- Reported, not fixed:
- Stale edits with a written key before a spread (main too).
- Import protection reports a dead re-export of a denied module with a top-level
await. - Import protection findings from code review, not run: a checked pattern plus an unchecked plain importer of one file depends on load order (
allowImportfollows the same order, documented), and CSSurl()of a denied file on Rsbuild builds a silent mock. Withsource.transformImport, an allowed re-export gets only the rewritten member.
- Upstream reports not filed yet: Rolldown keeping a plugin alive after
close()(Vite 8 retains its plugins), and Watchpack/Rspack compiling twice on a same-millisecond save. - Ports after merge: the "implementation obsolete" list below.
Upstream issues filed#
✅ fixed · ✖ closed without a fix · ○ open
Yuku: 27 ✅ fixed, 1 ✖ closed. Four of the fixes (#288, #289, #291, #292) shipped in Yuku 0.25.0 and #318 in 0.27.0; the PR pins 0.27.0. #290 was closed because the fix is deferred to Yuku's upcoming transformer; we don't need it.
All 28
✅ #202 purity comments · ✅ #203 codegen SIGBUS · ✅ #204 JSX refs for
_/$/Unicode · ✅ #229import X = ns.Y· ✅ #230 decorators afterexport· ✅ #231 JSXText entities · ✅ #232 false duplicate export · ✅ #237 empty JSX container comments · ✅ #244 WASM stale bytes · ✅ #247unwraptyping · ✅ #248copyAst()· ✅ #251export {} from· ✅ #252import()specifiers · ✅ #253 big-endian decoding · ✅ #254 JSX attribute mapping · ✅ #255 postfix++parens · ✅ #256for (init;;)no-in· ✅ #257 private method overloads · ✅ #258import type {}· ✅ #259super()in computed key · ✅ #260 JSX text after</>· ✅ #287(a?.b)!.c· ✅ #288 JSXText escaping · ✅ #289 stale JSXTextraw· ✖ #290stripkeeps type-only exports · ✅ #291 surrogate-pair spans · ✅ #292 Annex B functions · ✅ #318export namespace A.Binfile.exportsVite:
- ○ #23719 saves within 50 ms are ignored
- ○ #23907 the module graph keeps deleted files
- ○ vite-plugin-vue#866 a removed export breaks HMR accept
Rolldown:
Rspack:
Rsbuild:
- ✅ #8736 the dev FS keeps hot-update files (fixed in Rsbuild 2.3.0)
solid-refresh (all ○):
Others:
- ○ magic-string#368 only
\ncounts as a line break - ○ babel-dead-code-elimination#50
typeof xkeepsx - ○ webcontainer-core#2173
encodeInto('')returns stale data - ✅ tanstack.com#1353 the playground drops Start config
- ○ magic-string#368 only
Issues#
- Closes #7213
- Closes #8731
- Closes #7943
- Closes #8545
- Closes #8514
- Closes #8480
- Closes #7754
- Closes #8753
- Closes #8623
- Closes #8754
- Closes #8715
- Closes #8505
- Closes #8446
- Closes #8447
- Closes #8407
- Closes #8062
- Closes #7535
- Closes #7280
- Closes #6667
- Closes #7921
- Closes #7216
- Closes #8543
- Closes #8544
- Closes #8688
- Closes #8614
- Closes #8794
- Closes #6451
Other issues:
- #8437, partially addressed: Start's footer follows
quoteStyle/semicolons, buttsr generatestill writes none. - #6451, a Vite race fixed in Vite 8.2.2 (vitejs/vite#23009): main's peer range still allows 8.0–8.2.1. This PR compiles server fns in place, so it avoids the race on any Vite.
- #5721, not fixed here: it is already fixed on main.
- #8139, not fixed here: it is rolldown#11341, now fixed upstream. On an older Rolldown, set
strictExecutionOrder: trueonssr.
Supersedes #8805, #8504, #8630, #8721, #8780, #8773, #8756, #8755, #8732, #8686, #8682, #8681, #8061, #8541, #8493, #8481, #8459, #8455, #7892, #8515, #7281, #8269, #8628, #8797, #8662, #8296, #8215, #8454, #8276, #8675, #8540, #8523, #8524, #8680, #8684, #8642, #8749, #8801, #7338, #8656, #8798, #8818
Implementation obsolete (still needs a re-port after merge): #8804, #7693, #7766, #7872, #8291, #8293, #8277, #8799, #8800, #6748, #8256, #8057, #7925
How to review#
The compiler-tests/baseline branch accounts for most of the diff, and most of the rest is tests and regenerated route trees. Product code is in packages/*/src.
- Core: start with
router-utils/src/compiler/README.md, then readidentity→source/analysis→units/mutation→rewrite→reach→plan→emit→values/summary/facts→cache/pipeline→verify. Keeptests/helpers.tsandtests/placement.test.tsopen alongside. - Planners:
- Router:
router-plugin/ARCHITECTURE-CODE-SPLITTING.md, thensrc/planners/. - Start:
start-plugin-core/src/planners/(start-env,hydrate,rsc-css,edges), withsrc/compiler/,src/server-fns/andsrc/import-protection/. Builder escapes:ESCAPE_MESSAGESinstart-env.tsandtests/planners/start-builder-shapes.test.ts.
- Router:
- Hosts:
router-plugin/src/hosts/.- Start's
src/vite/compiler-plugin.ts. - Start's
src/rsbuild/(readCOMPILER_ARCHITECTURE.mdfirst).
- Generator and runtime:
router-generator(AGENTS.md,analyze/,model/,print/).router-core/src/hmr.tsand{react,solid,vue}-router/src/hmr.ts.start-client-core/src/createServerFn.ts.
- Tests: the oracle's
README.md,SPEC.mdandKNOWN-BUGS.md.
To reproduce the measurements, see:
packages/compiler-test-utils/oracle/README.mdbenchmarks/compiler-perf/README.md(run.mjs,compare.mjs,soak-analyze.mjs)pnpm benchmark:bundle-size:runscripts/benchmarks/bundle-size/server.mjs
This PR was written with AI assistance: Claude Code agents working under a human architect. Their work was checked against the oracle, e2e, perf and bytes gates above.
🤖 Generated with Claude Code
- 1
🦋 Changeset detected#
Latest commit: eb1a7841bb09858cf5a609e426596d8c012de762
The changes in this PR will be included in the next version bump.
This PR includes changesets to release 24 packages
Name Type @tanstack/start-plugin-core Minor @tanstack/react-start Minor @tanstack/solid-start Minor @tanstack/vue-start Minor @tanstack/react-start-rsc Minor @tanstack/router-utils Minor @tanstack/router-plugin Minor @tanstack/router-generator Minor @tanstack/router-cli Patch @tanstack/router-core Patch @tanstack/react-router Patch @tanstack/solid-router Patch @tanstack/vue-router Patch @tanstack/router-vite-plugin Patch @tanstack/react-start-client Patch @tanstack/react-start-server Patch @tanstack/solid-start-client Patch @tanstack/solid-start-server Patch @tanstack/start-client-core Patch @tanstack/start-server-core Patch @tanstack/start-storage-context Patch @tanstack/vue-start-client Patch @tanstack/vue-start-server Patch @tanstack/start-static-server-functions Patch 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
github-actions[bot](GitHub profile, opens in a new tab) added labelsdocumentation
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: react-router
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-core
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-generator
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: router-cli
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: solid-router
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: react-start
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: start-plugin-core
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: start-client-core
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: vue-router
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: react-start-rsc
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
Diff Package Supply Chain
SecurityVulnerability Quality Maintenance License @rsbuild/plugin-solid@1.1.1 ⏵ 1.2.2 +1
+1
+2
@rspack/core@2.2.7 ⏵ 2.2.9 +1
+1
vite@7.3.7 vite@6.4.5 @mdx-js/rollup@3.1.1 @mdx-js/loader@3.1.1 @rsbuild/core@2.2.5 ⏵ 2.2.14 +1
+1
react-error-boundary@6.1.6 exsolve@1.1.1 ⏵ 1.1.3 +1
+1
yuku@0.27.0 @workos/authkit-tanstack-react-start@0.5.0 ⏵ 0.12.0 +18
+1
-1
@workos-inc/node@8.0.0 ⏵ 10.14.0 Warning
Review the following alerts detected in dependencies.
According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.
Priority Alert (click "▶" to expand/collapse) Action Low adoption: npm
@yuku-toolchain/darwin-arm64Location: Package overview
From: pnpm-lock.yaml →
npm/yuku@0.27.0→npm/@yuku-toolchain/darwin-arm64@0.27.0ℹ Read more on: This package | This alert | What are unpopular packages?
Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at
support@socket.dev.Suggestion: Unpopular packages may have less maintenance and contain other problems.
Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment
@SocketSecurity ignore npm/@yuku-toolchain/darwin-arm64@0.27.0. You can also ignore all packages with@SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.Warn
Low adoption: npm
@yuku-toolchain/darwin-x64Location: Package overview
From: pnpm-lock.yaml →
npm/yuku@0.27.0→npm/@yuku-toolchain/darwin-x64@0.27.0ℹ Read more on: This package | This alert | What are unpopular packages?
Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at
support@socket.dev.Suggestion: Unpopular packages may have less maintenance and contain other problems.
Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment
@SocketSecurity ignore npm/@yuku-toolchain/darwin-x64@0.27.0. You can also ignore all packages with@SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.Warn
Low adoption: npm
@yuku-toolchain/linux-arm64Location: Package overview
From: pnpm-lock.yaml →
npm/yuku@0.27.0→npm/@yuku-toolchain/linux-arm64@0.27.0ℹ Read more on: This package | This alert | What are unpopular packages?
Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at
support@socket.dev.Suggestion: Unpopular packages may have less maintenance and contain other problems.
Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment
@SocketSecurity ignore npm/@yuku-toolchain/linux-arm64@0.27.0. You can also ignore all packages with@SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.Warn
Low adoption: npm
@yuku-toolchain/win32-arm64Location: Package overview
From: pnpm-lock.yaml →
npm/yuku@0.27.0→npm/@yuku-toolchain/win32-arm64@0.27.0ℹ Read more on: This package | This alert | What are unpopular packages?
Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at
support@socket.dev.Suggestion: Unpopular packages may have less maintenance and contain other problems.
Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment
@SocketSecurity ignore npm/@yuku-toolchain/win32-arm64@0.27.0. You can also ignore all packages with@SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.Warn
Low adoption: npm
@yuku-toolchain/win32-x64Location: Package overview
From: pnpm-lock.yaml →
npm/yuku@0.27.0→npm/@yuku-toolchain/win32-x64@0.27.0ℹ Read more on: This package | This alert | What are unpopular packages?
Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at
support@socket.dev.Suggestion: Unpopular packages may have less maintenance and contain other problems.
Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment
@SocketSecurity ignore npm/@yuku-toolchain/win32-x64@0.27.0. You can also ignore all packages with@SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.Warn
View your CI Pipeline Execution ↗ for commit eb1a7841bb09858cf5a609e426596d8c012de762
Command Status Duration Result nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded 18m 28s View ↗ nx run-many --target=build --exclude=examples/*...✅ Succeeded 1m 42s View ↗
☁️ Nx Cloud last updated this comment at
2026-11-04 06:03:43UTC🚀 Changeset Version Preview#
15 package(s) bumped directly, 9 bumped as dependents.
🟨 Minor bumps#
Package Version Reason @tanstack/react-start1.169.4 → 1.170.0 Changeset @tanstack/react-start-rsc0.1.65 → 0.2.0 Changeset @tanstack/router-cli1.167.46 → 1.168.0 Changeset @tanstack/router-core1.171.39 → 1.172.0 Changeset @tanstack/router-generator1.167.46 → 1.168.0 Changeset @tanstack/router-plugin1.168.48 → 1.169.0 Changeset @tanstack/router-utils1.162.4 → 1.163.0 Changeset @tanstack/solid-start1.169.4 → 1.170.0 Changeset @tanstack/start-plugin-core1.171.55 → 1.172.0 Changeset @tanstack/vue-start1.169.4 → 1.170.0 Changeset 🟩 Patch bumps#
Package Version Reason @tanstack/react-router1.170.46 → 1.170.47 Changeset @tanstack/react-start-client1.168.44 → 1.168.45 Changeset @tanstack/solid-router1.170.43 → 1.170.44 Changeset @tanstack/start-client-core1.170.39 → 1.170.40 Changeset @tanstack/vue-router1.170.42 → 1.170.43 Changeset @tanstack/react-start-server1.167.52 → 1.167.53 Dependent @tanstack/router-vite-plugin1.167.48 → 1.167.49 Dependent @tanstack/solid-start-client1.168.42 → 1.168.43 Dependent @tanstack/solid-start-server1.167.50 → 1.167.51 Dependent @tanstack/start-server-core1.169.45 → 1.169.46 Dependent @tanstack/start-static-server-functions1.167.44 → 1.167.45 Dependent @tanstack/start-storage-context1.167.41 → 1.167.42 Dependent @tanstack/vue-start-client1.167.45 → 1.167.46 Dependent @tanstack/vue-start-server1.167.50 → 1.167.51 Dependent Bundle Size Benchmarks#
- Commit:
e909efadf3fb - Measured at:
2026-11-04T05:43:29.011Z - Baseline source:
history:da8c28c49823 - 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.full99.8 KiB
-52 B99.7 KiB
-52 B311.6 KiB
-48 B86.6 KiB
+86 B███████████▁
react-start.rsbuild.minimal100.3 KiB
-8 B100.2 KiB
-9 B313.2 KiB
-22 B86.6 KiB
-1 B▁▁▁▁▁▁▁▁▁▁█▂
react-start.rsbuild.minimal-iife100.8 KiB
-11 B100.6 KiB
-12 B314.2 KiB
-22 B87.0 KiB
-2 B▁▁▁▁▁▁▁▁▁▁█▃
react-start.rsbuild.full103.5 KiB
-45 B103.3 KiB
-46 B322.9 KiB
-62 B89.3 KiB
+72 B▇▇▇▇▇▇▇▇▇▇█▁
solid-start.full51.1 KiB
-42 B51.0 KiB
-44 B150.0 KiB
-48 B45.4 KiB
-104 B███████████▁
vue-start.full69.1 KiB
-42 B68.9 KiB
-43 B197.5 KiB
-48 B61.6 KiB
-24 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:
🤖 Written by Claude (AI) at the maintainer's request; numbers are from this PR's perf harness and CPU profiles, reviewed by a human.
Headroom after this PR (338-route apps, median ms; real = final perf matrix at c4cb7e889a; floor = every compiler output replayed, i.e. a zero-cost compiler, from the earlier 498ac9be17 run. The two come from different runs, so treat ±8% as noise):
app build real / floor / ours dev cold → /hydrateddev compile-all react-start 1,634 / 779 / 855 2,561 / 1,581 / 980 2,038 / 1,055 / 983 react-router 612 / 419 / 193 1,046 / 856 / 190 1,303 / 996 / 307 solid-start 4,375 / 3,283 / 1,092 3,406 / 2,348 / 1,058 4,624 / 3,693 / 931 solid-router 1,982 / 1,875 / 107 1,490 / 1,317 / 173 4,049 / 3,764 / 285 Compiler-only work can still win at most ~0.2–0.3 s on Router and ~1 s on Start, for React and Solid alike. Solid's floor is 1.5–4× React's because of
vite-plugin-solid's Babel pass, which we don't own. Anything bigger means making the bundler do less.HMR: route, loader and server-fn edits are 15–84% faster than main. Shared-module edits are at or below main in every cell and don't grow with app size (large React Start −2.40 ms [−2.70, −2.10], Solid Start −2.15 [−2.40, −1.90], React Router −0.10 [−0.40, 0.20]; React Start 23.2/23.6/23.5 ms small→large vs main 23.4/24.1/25.6).
Where the Start second goes: the last full profile was taken before the final perf pass (Yuku 216 ms, own core 455, Start planners ~85, libraries ~12). That pass cut per-module core time by 12–23% in-process and compile-all by ~6% end to end. It took tier-0 bindings from
file.imports[].local, computed the plan fingerprint lazily, madeedgeKey/canonicalJsoncheaper, ran hit validation in parallel and skipped emission for identity outputs. Re-profile before picking the next own-code target. Sync time in ourtransformhooks is ~200 ms; the rest runs after awaits, mostly resolutions.Dev startup#
Lazy route modules (router-core + generator, not the compiler). Loading
/transforms 488 client + 469 SSR modules because the generated tree imports every route file; ~1.35 s of that is bundler time even with a free compiler. The idea: a tree whose unmatched routes carry only path info andimport()their file on first match. Est. 2.6 s → 0.7–0.9 s (react-router 1.0 → ~0.4). It would also connect the dev client earlier: Start's dev entry imports/@vite/clientstatically, so HMR connects only once the whole route graph is fetched. Effort high (match-time loading, types, Start manifest, HMR); risk: pathless/beforeLoad-only ancestors.Resolve less. Start's value prefetch resolves every value-referenced import through the bundler's resolver, and import protection resolves every edge: ~8.4k distinct resolutions per compile-all. The old estimate (0.3–0.4 s, from "+18% without the resolution cache") is withdrawn. That cost was every plan hit re-validating its resolutions, which re-validating only after the file set changes now avoids, at parity with the cache. A Vite
resolveIdsettles in ~0.07 ms, so first-time resolutions sum to ≤ ~0.6 s of async time, mostly overlapped. Count and time them before building anything. Options:- Don't resolve bare specifiers that no alias/
pathscovers and that don't name a discovered Start library. On Vite they end up pre-bundled (opaque) or external (SSR) anyway. This also removes Vue's remaining shared-module HMR cost (3 resolver calls per edit vs main's 2). - A stat-probe fast path for
.//../, with bundler fallback and a dev-mode self-check. - Read target markers only when a marker-bearing file exists (index once, keep it via the watcher).
Effort low–medium; risk: resolver plugins we bypass.
- Don't resolve bare specifiers that no alias/
Gate the Vite host like Rsbuild.Done: one compile-scope rule for both hosts (a dependency is compiled only if import protection's scope includes it or its text names a Start API), asset queries excluded, no no-op rewrites. On tanstack.com this turned a +30% build regression into −24% vs main.Pre-bundle Start's late dependencies.
seroval,seroval-plugins/webandcookie-esare found only while the first page is served, on all three frameworks and on main too, so the optimizer re-runs (~0.75 s measured on Vue). Adding them to the clientoptimizeDeps.include(nested@tanstack/<fw>-start > …form) avoids that on the first start, or after a lockfile change. Effort trivial; verify that it is on the hydration critical path for React/Solid first.Listen ~212 ms (react-start medium): generator 40, plugin import ~65 (zod 11.5). ≤ 30 ms left. Swapping zod changes public config types in three packages.
Build / compile-all#
One plan for both envs when nothing env-specific happened. SSR compile-all is 903 real vs 461 floor. Most route files have no server code, so their SSR plan equals the client plan. Serve the second env from the first plan when it recorded no Start candidate (edge policy is already per output). Est. 200–300 ms on Start, 0 on Router. Risk: per-env resolvers; validate fingerprints under the second env.
Yuku JS side (asks drafted, not filed): O(1)
indexOf, index-based node views, native side-effect query. The ~35 / 70–100 / 40 ms estimates predate tier 0 readingfile.imports[].local: modules that never reach tier 1 no longer build the node→index map, so re-measure the gain before filing.Own code:
- Placement fast path for one split group with no shared candidates (~15 ms); an invariant checker first, so it can't diverge silently.
- Memoise
dependencyPathson the plan. - Drop the facts deep clone in
freeze().
Honest total ≤ 50–100 ms; re-profile first.
Persistent plan cache across restarts: correct by construction (plans are pure in (env, source, config, summaries) and carry dependency fingerprints), but it skips only our part. After a restart every recorded resolution must be re-validated once, so it also pays (2). Est. compile-all 2.0 → ~1.5 s, cold 2.6 → ~2.1. Better to wait for a bundler-side transform cache (Rsbuild already replays our
buildInfo), which also skips oxc/refresh (~0.6 s of the floor).Workers / Rust: no. Sync hook time is ~200 ms; the wait is resolver round-trips, which a worker cannot shorten, and summaries/registries would have to be shared. Revisit for builds only after (2).
The generator's
configResolvedruns 3× in builds (94 ms vs 40 in dev). Run it once: −50 ms.
Memory#
Dev heap after GC (react-start medium) is 87 MB after
/hydrated and 72 MB after compile-all (main: 212 / 282). Ours ≈ plans 11.9 MB (1,038 × ~11.5 KB) + raw facts 0.7. Removing the resolution cache and the emitted-output memo took 5–13 MB off. Next: intern repeated dependency fingerprints and segment arrays inEmitPlan(−5…7 MB). The rest is upstream and now filed: Vite keeps module-graph nodes of deleted files (~2 KB each, vitejs/vite#23907), and Rsbuild's memfs keeps every hot-update asset (~260 KB per edit, web-infra-dev/rsbuild#8736).Bytes#
Client: Router is byte-identical; Start is −35…−47 B gzip (shorter server-fn ids). Rsbuild minimal is +1/+3 B gzip (Rspack renumbers module ids; raw −22). Server: Vite −12…−823 B raw. react-start.rsbuild.full is +432 raw / +132 gzip because the handler stays in its module, so Rspack loses scope hoisting. A cache group that merges the provider chunk into the router chunk recovers part of it, but is blocked by an Rspack panic (web-infra-dev/rspack#16289).
Route files importing another route file's export. A route file that imports an exported component or helper from another route file (
import { ProductPage } from './shop.products.$handle') imports it through that route module, which the route tree loads eagerly. The route module's static re-export of the extracted module is then used, so the extracted module and its imports land in the entry chunk, even when every user is a split component (tanstack.com:ProductPage, ~7.5 KB of initial JS). When the importer is itself a route file we compile, the compiler could point the import straight at the extracted module (…?tsr-split=export~ProductPage): the route module's re-export stays unused and is tree-shaken, the binding stays lazy, with no copy and no user change. Route-to-route imports are common, so this could be a significant initial-load win. Needs a spike: HMR identity, the warning that currently tells users to move the export, Rsbuild/webpack.Effect-free built-in constructors. A module-level
new X()counts as a side effect (as in Rollup/Rolldown/esbuild), soconst fmt = new Intl.NumberFormat(…)used only by a split component can stay in the route module or pin an earlier declaration (the build now warns). Sound next step: treat standard built-in constructors that are provably effect-free (Map,Set,WeakMap,URL,URLSearchParams,Intl.*formatters,TextEncoder/TextDecoder,AbortController, …) as pure when called with pure arguments, recognised by binding to the global (never when shadowed), like the TanStack pure-API table. Third-party constructors stay effectful (new WebSocket(), analytics clients andnew JSConfetti()do real work). First count, across the corpus and the large apps, which constructors actually pin split-only code, to size the gain.Route CSS stays eager, as on main; fully lazy route CSS needs a per-route asset loader in router-core. Root routes stay unsplit: splitting their error/notFound components cost SSR CPU, and the manifest preloaded that chunk on every page anyway.
shared~a+bmodules andexport~Nameforwarders cost one request each; a route-awareadvancedChunkshint trades requests, not bytes. Nothing else material.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@8817@tanstack/eslint-plugin-router
npm i https://pkg.pr.new/@tanstack/eslint-plugin-router@8817@tanstack/eslint-plugin-start
npm i https://pkg.pr.new/@tanstack/eslint-plugin-start@8817@tanstack/history
npm i https://pkg.pr.new/@tanstack/history@8817@tanstack/react-router
npm i https://pkg.pr.new/@tanstack/react-router@8817@tanstack/react-router-devtools
npm i https://pkg.pr.new/@tanstack/react-router-devtools@8817@tanstack/react-router-ssr-query
npm i https://pkg.pr.new/@tanstack/react-router-ssr-query@8817@tanstack/react-start
npm i https://pkg.pr.new/@tanstack/react-start@8817@tanstack/react-start-client
npm i https://pkg.pr.new/@tanstack/react-start-client@8817@tanstack/react-start-rsc
npm i https://pkg.pr.new/@tanstack/react-start-rsc@8817@tanstack/react-start-server
npm i https://pkg.pr.new/@tanstack/react-start-server@8817@tanstack/router-cli
npm i https://pkg.pr.new/@tanstack/router-cli@8817@tanstack/router-core
npm i https://pkg.pr.new/@tanstack/router-core@8817@tanstack/router-devtools
npm i https://pkg.pr.new/@tanstack/router-devtools@8817@tanstack/router-devtools-core
npm i https://pkg.pr.new/@tanstack/router-devtools-core@8817@tanstack/router-generator
npm i https://pkg.pr.new/@tanstack/router-generator@8817@tanstack/router-plugin
npm i https://pkg.pr.new/@tanstack/router-plugin@8817@tanstack/router-ssr-query-core
npm i https://pkg.pr.new/@tanstack/router-ssr-query-core@8817@tanstack/router-utils
npm i https://pkg.pr.new/@tanstack/router-utils@8817@tanstack/router-vite-plugin
npm i https://pkg.pr.new/@tanstack/router-vite-plugin@8817@tanstack/solid-router
npm i https://pkg.pr.new/@tanstack/solid-router@8817@tanstack/solid-router-devtools
npm i https://pkg.pr.new/@tanstack/solid-router-devtools@8817@tanstack/solid-router-ssr-query
npm i https://pkg.pr.new/@tanstack/solid-router-ssr-query@8817@tanstack/solid-start
npm i https://pkg.pr.new/@tanstack/solid-start@8817@tanstack/solid-start-client
npm i https://pkg.pr.new/@tanstack/solid-start-client@8817@tanstack/solid-start-server
npm i https://pkg.pr.new/@tanstack/solid-start-server@8817@tanstack/start-client-core
npm i https://pkg.pr.new/@tanstack/start-client-core@8817@tanstack/start-fn-stubs
npm i https://pkg.pr.new/@tanstack/start-fn-stubs@8817@tanstack/start-plugin-core
npm i https://pkg.pr.new/@tanstack/start-plugin-core@8817@tanstack/start-server-core
npm i https://pkg.pr.new/@tanstack/start-server-core@8817@tanstack/start-static-server-functions
npm i https://pkg.pr.new/@tanstack/start-static-server-functions@8817@tanstack/start-storage-context
npm i https://pkg.pr.new/@tanstack/start-storage-context@8817@tanstack/valibot-adapter
npm i https://pkg.pr.new/@tanstack/valibot-adapter@8817@tanstack/virtual-file-routes
npm i https://pkg.pr.new/@tanstack/virtual-file-routes@8817@tanstack/vue-router
npm i https://pkg.pr.new/@tanstack/vue-router@8817@tanstack/vue-router-devtools
npm i https://pkg.pr.new/@tanstack/vue-router-devtools@8817@tanstack/vue-router-ssr-query
npm i https://pkg.pr.new/@tanstack/vue-router-ssr-query@8817@tanstack/vue-start
npm i https://pkg.pr.new/@tanstack/vue-start@8817@tanstack/vue-start-client
npm i https://pkg.pr.new/@tanstack/vue-start-client@8817@tanstack/vue-start-server
npm i https://pkg.pr.new/@tanstack/vue-start-server@8817@tanstack/zod-adapter
npm i https://pkg.pr.new/@tanstack/zod-adapter@8817commit:
eb1a784Merging this PR will improve performance by 1.51%#
2 warnings, 1 note
:warning: 49 benchmarks are dominated by system calls
System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.
:warning: 2 benchmarks with a significant change ran on different hardware
Their base and head results were measured on machines with a different CPU, core count or memory, so the changes might not come from the code. Run base and head on the same runner type.
Learn more about Macro Runners
:information_source: 20 benchmarks have no flamegraph
The flamegraph wasn't generated: most of the time was spent in runtime internals, which would leave nothing useful to analyze.
⚡ 1improved benchmark❌ 1 (👁 1)regressed benchmark✅ 192untouched benchmarks⏩ 3skipped benchmarks1Performance Changes#
Mode Benchmark BASEHEADEfficiency 👁 Memory mem client interrupted-navigations (solid)83.8 KB 86.9 KB -3.53% 👁 Memory mem client navigation-churn (solid)112.8 KB 105.6 KB +6.81% Tip
Curious why performance improved? Comment
@codspeedbot explain why performance improvedon this PR, or directly use the CodSpeed MCP with your agent.
Comparingcompiler-rewrite/yuku(eb1a784) withmain(da8c28c)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. ↩
-
🤖 Written by Claude (AI) at the maintainer's request, from a brainstorm over this PR's architecture; reviewed by a human. Revised after later changes to the branch.
What this rewrite unlocks. Before: each transform re-parsed the previous one's output, APIs were matched by name, removal was guessed. Now: one shared analysis per module, recognition by binding identity across re-exports, edits on original ranges with exact maps, and per-output placement by reachability. Effort: S = days, M = weeks, L = a quarter.
Top picks#
- More lint-like diagnostics with exact positions: e.g. "server fn handler closes over mutable module state", "loader imports a component-only module" → the compiler already knows bindings, which output a reference lands in, and original line:col; positioned warnings already ship for unreadable route options and options that stay unsplit, on every bundler → S–M per rule → broken splits and leaks caught at build time, clickable in the Vite overlay and Rspack/webpack output.
- Compile-time route manifest + preload hints: route → split modules and server fn ids come from compile results; only file names come from the bundle (today the manifest scans client chunks for route files) → M → exact
Linkpreloads, per-routemodulepreload/early hints, fewer waterfalls. createServerFn({ serializable: true }): a server fn opted into being sent to the client as data gets a real client builder and is always HTTP-callable → the builder chain is a recognised value; the HTTP-callable set is already collected → S–M → fixes client middleware never running for serialised server fns, instead of a production rejection.const getUser = createServerFn({ serializable: true }) .middleware([authClientMiddleware]) .handler(() => …) // returned from a loader: callable on the client, client middleware runs- User planner API: Babel-free replacement for the removed compiler hooks: read the module analysis, emit edits, outputs, diagnostics → the built-in transforms already use this contract; the internal one hands planners Yuku nodes, so a public version needs a facts-only view or a promise about Yuku's AST → M (mostly the stability promise) → i18n extraction, custom rules, RSC integrations without forking.
- Lazy route modules (router-core): path-only route shells that
import()the file on first match → the generator has a pure route model; unvisited files stay cold → L (match-time loading, types, manifest, HMR) → largest dev-startup win left (see perf comment). - Automatic server/client boundary inference: split mixed modules per env; treat modules reachable only from server handlers as server-only without a marker → markers are per-file facts and placement already decides per output → M–L, needs semantics design → fewer
.server.tsfiles and leaks.
Also enabled#
Compiler APIs
ssr: falseroute code pruned from server output → placement decides per output; the route model needs each file'sssroption and its inheritance → M → no server evaluation of browser-only modules.- Split
head/scripts(awaited after loaders, like a splitloader) → a new split key is a declared root → S each.validateSearch/paramsschemas run synchronously during matching, so splitting them needs async validation in router-core → M–L. - User-defined env markers (e.g. edge-only fns) → recognisers are pluggable; marker kinds and envs are server/client today → M → compile-time pruning for custom runtimes.
Diagnostics / devtools
- "Why is this in my client bundle?" / "why didn't this split?": root → code chain per output as JSON, plus the fallback reasons the splitter already reports → S.
- Devtools panel showing per-route compile facts (split groups, server fn ids, import-protection verdicts) → M.
- Compile-time
Linkchecks (unknown routes, missing params) for JS projects and dynamic strings → route model +Linkrecognisable by binding → M.
Routing
- Fully lazy route CSS, loaded on match regardless of components → route CSS stays in the route module as on main; the compiler can list each route's style imports, router-core needs a per-route asset loader → M → per-route CSS without the eager bundle.
- Cross-file shared-module placement (one lazy module for helpers several routes need) → M → fewer duplicated bytes.
RSC
'use client'reference stubs and'use server'as planners in the same pass → per-env directive policy exists → M → one model for server fns and RSC.
Bundlers
- esbuild
autoCodeSplitting(refused today) → the core is host-agnostic and derived-module ids work on every bundler → M (side-effects handling). - Bun/Farm hosts → a router host is ~500–700 lines over the same core and behaviour suite (Start's is larger) → M each.
tsr compileCLI over a directory → S → debugging, codemods.
Maintenance: React/Solid/Vue share every planner, so features reach all three at once.
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: vue-start
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: solid-start
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: react-start-client
Sign in to join this conversation.
Important
Draft PR not reviewed#
Draft PRs are not automatically reviewed by default.
To automatically review draft PRs, update your CodeRabbit configuration:
Tip
🎯 Customize your risk assessments
Guide how CodeRabbit assesses merge risk and security architecture risk. Highlight sensitive changes and explain your security boundaries using Merge Risk Instructions and Security Risk Instructions in your review settings. Security architecture risk assessments require the Advanced plan or above.
✅ Automatic approvals, with your rules
Let CodeRabbit approve pull requests once required threads are resolved, pre-merge checks pass, and your risk limits are met. Enable Automatic approvals in review settings, with overrides for teams or file paths.
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