Skip to content
Source
Sign inSign up
TanStack/router

refactor(compiler)!: replace Babel with a Yuku-based compiler core for Router and Start #8817

OpenSheraff(GitHub profile, opens in a new tab)wants to merge 250+ commits intomain fromcompiler-rewrite/yukuopened

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 of Route are answered from the route registry instead of a read of every route file. The JavaScript of .mdx, .vue, .svelte, .astro and .marko modules gets a late pass with import protection and start-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. OutputBuilder writes 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-env tracks 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 (with buildInfo replay 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 appbuilddev cold → hydratedcompile-allHMR route editdev heap after GC
react-start Vite31,193 → 9,31625,577 → 7,90731,528 → 8,94564.8 → 41.5703 → 211
react-start Rsbuild ¹27,443 → 6,13232,138 → 6,554–1,814 → 1,452 (n.s.)730 → 228
react-router Vite11,789 → 3,37811,835 → 3,23927,084 → 5,46853.8 → 31.6103 → 92.0 (n.s.)
solid-start Vite44,295 → 20,60031,778 → 10,93544,240 → 19,701– ²618 → 210 ²
solid-router Vite17,813 → 8,53914,723 → 4,64541,482 → 15,770875 (full reload) → 19.892.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, b7a8d45b2b vs 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 against eb12efe304, 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 at 76ddc5e13e, identical output). The follow-up rounds through 5bc674ea80 added no measurable cost: against eb12efe304, 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] at f7664a8e8b (a separate run: −0.32% [−1.37, 0.73]) and solid-start client −1.47% [−2.58, −0.20] at 3ee403ebeb. 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 at fa6a9906ed. 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. b7a8d45b2b lands in the same mode in 4 of 12 rounds, and with --max-old-space-size=640 both 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 build with 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 (b7a8d45b2b vs e536af167a, 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 and navigation-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.
  • e18e framework tracker (their harness and starter on 2 CPUs, 12 paired rounds, b7a8d45b2b vs 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 at da12a6f6ba, 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.

cellbuilddev listendev cold → hydratedcompile-alldev heap after GCbuild peak RSS
react-start Vite medium6,898 → 1,921745 → 3166,393 → 2,9237,625 → 2,287212 → 91.61,041 → 749
react-start Vite large31,193 → 9,3161,572 → 45225,577 → 7,90731,528 → 8,945703 → 2112,335 → 1,251
react-start Rsbuild medium6,746 → 1,894203 → 1697,727 → 2,115–217 → 98.3971 → 742
react-start Rsbuild large27,443 → 6,132210 → 15832,138 → 6,554–730 → 2282,634 → 1,685
react-start-deps Vite medium ³7,397 → 2,204756 → 2187,056 → 3,4428,423 → 2,602234 → 1101,155 → 840
react-router Vite medium2,944 → 740645 → 1813,646 → 1,1346,886 → 1,48063.8 → 48.7630 → 435
react-router Vite large11,789 → 3,3781,391 → 28411,835 → 3,23927,084 → 5,468103 → 92.01,113 → 746
solid-start Vite medium9,913 → 4,718771 → 2617,770 → 3,48211,222 → 4,874191 → 94.61,317 → 974
solid-start Vite large44,295 → 20,6001,607 → 36731,778 → 10,93544,240 → 19,701618 → 210 ²2,761 → 2,140 ²
solid-router Vite medium4,496 → 2,104633 → 2564,099 → 1,74110,436 → 4,45363.0 → 55.7688 → 600
solid-router Vite large17,813 → 8,5391,521 → 34714,723 → 4,64541,482 → 15,77092.5 → 92.81,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.
    • *.full scenarios are −38…−52 B gzip, thanks to shorter server-fn ids. They include a scenario edit (−6 B raw): the old *-start.full source 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/.mjs summed per server directory, gzip −9; these totals don't match server.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 __root a 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).
  • 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)
tests3,5946,070
known-bug pins (.fails)87477
non-pin failures00
  • 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, against 758377e4d2) 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-adapters stream: the router's $_TSR.e() deletes $_TSR before Solid's last script reads it. It fails on main too (main 4/20, b7a8d45b2b 5/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, on b7a8d45b2b and 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_RESOURCES in 8 of 36 runs on each side (eb12efe304 and this branch, one side at a time), with the same shape. Not a regression.
    • <Hydrate> page tests: the harness's settled() could return before a visible() 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 after settled() 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 at e27395a033): the test took 1,027 ms against Testing Library's 1,000 ms findByText default (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 at a5ca5977da, and 1,758.2 MB at 17e475671e (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-start 0.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-basic fails 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 --watch and 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 37e941dfe6 by 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 tsconfig paths and by design for the rest.
  • 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.json imports/exports edits 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 constructor or __proto__ finding Object.prototype in a table and failing the build;
      • a plugin giving a route and its chunk different text, now the input-text-differs warning.
    • False, or not a regression: buildItems, regionReads and setImmediate per 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.
  • 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 fa6a9906ed and 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__ */ then mk() 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 (a TypeError at 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), with beforeLoad writing prefix) 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.ts with a regular file; it writes through the link;
    • Rsbuild on Windows treating a package.json edit 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 comp in a nested var { comp = 1 } = o, and of an annotated const comp: FC in 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 node exports failed with Errored while resolving instead 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 a sideEffects: false package; and, with an allowed import, build --watch wrote no client and rsbuild build never 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/traverse copies, 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 purpose20Route CSS applies only once the route matches. This needs a per-route asset loader (follow-up).
16A 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)10An 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.
5An importer outside srcDirectory/include gets the real module of an in-scope denied file it imports. It gets the mock, for the same reason.
1An 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 limitation6A 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).
4On 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 main5These 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 limitation3On rspack/webpack/rsbuild without sideEffects, an exported component another route's chunk imports loads with that chunk.
1On Rsbuild dev, a custom module type (.page as javascript/auto) importing a denied specifier is reported. Rspack rules select by resource.
1On Rsbuild build, an unused exported component with a boundary emits no async chunk.
1On 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.
Upstream1On Rsbuild dev, adding a route's first server fn shows on the open page (rspack#16288).
1On 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 yet1In Vite bundledDev, a factory that becomes a server-fn builder keeps its handler. This needs the full-bundle API.
Accepted shape outcome1withBuilder(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 if with two returns, or an async function, method or getter. Also a let builder reassigned with something else, a builder in a TS namespace, and a project namespace object passed around when its module exports a builder.
    • A client-only createIsomorphicFn().client(fn) or createMiddleware().client(fn) passed to other code: use createClientOnlyFn(fn).
    • A parameter passed directly as server code: (fn) => createServerOnlyFn(fn), ({ handler }) => createMiddleware().server(handler), .validator(param).
    • RSC: renderServerComponent or createCompositeComponent outside a server function.
    • A route factory call the planner doesn't own (not export const Route = createFileRoute(path)(options)) that carries server, ssr or headers. 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 single return, export * as ns, a let reassigned with a builder of the same kind, a const middleware list, and createServerFn.call(thisArg, options).
  • 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, ssr or headers written 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 warm buildCache rebuilds.
  • 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 generate and builds reject, naming the file, the root route included. A dev server or watch session warns and keeps the last good route.
  • routeTree.gen.ts formatting changes once. The file is printed in your quoteStyle/semicolons. enableRouteTreeFormatting now defaults to false (true uses 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.generateFunctionId receives main's handler name as functionName (greetUser_createServerFn_handler, with _n for 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 500 TypeError.
  • vite build --watch of 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 memo or forwardRef whose 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. Vue defineComponent({ 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-differs warning 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 a Route that 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). allowImport runs during the build, before the import is replaced by its mock, in dev and builds, once per import; true gives the real module from the first pass, with no report. It also sees imports tree-shaking removes later, and its info has no trace or snippet. onViolation runs after the build, for imports that survive tree-shaking and weren't allowed, and changes nothing. Returning false from it no longer allows the import: the import gets the normal outcome, and Start prints a message pointing to allowImport. On main, false silenced 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 with error for specifier and marker imports. A build runs each environment once: there's no rebuild pass, and Start no longer patches Vite's builder.build. With RSC, a 'use client' file allowed from rsc is the real module in ssr too;
    • 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, template import(), 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 with error now 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.warmup glob).
  • 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 addHmr is 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 /hmr entry, 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:1 or none. The router plugin's loader errors are named TanStackRouterCompilerError.
  • Rsbuild:
    • Vue SFCs (@rsbuild/plugin-vue, or vue-loader through tools.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.enabled dev serves the shell;
    • server.compress is 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 now vite ≥ 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 --watch picks 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).
  • Solid Start server envs split like the client. Vue Start dev no longer reloads after dependency optimization.
  • Requirements:
    • @babel/core is no longer transitive, so declare it if a plugin needs it (e.g. React Compiler).
    • router-plugin's unplugin stays at main's ^3.5.0.
  • Removed:
    • Babel-typed experimental hooks: Start compilerTransforms, serverFnProviderModuleDirectives and StartCompilerPlugin;
    • react-start-rsc/plugin/rscCssTransform, replaced by rsc: { loadCssExpression, providerDirective };
    • router-utils' Babel helpers (router-utils gains /compiler);
    • router-generator's format, inferFullPath, checkRouteFullPathUniqueness and writeIfDifferent. onRouteTreeChanged now receives { model };
  • New dev-only subpaths: @tanstack/router-core/hmr and @tanstack/{react,solid,vue}-router/hmr.
  • Vue <script setup> (known limitation): on vite 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 .ts module 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/node as a dependency (the kit's peer), sign-in through a /api/auth/sign-in server route (the kit's per-flow PKCE cookies), Start's CSRF middleware added before authkitMiddleware() (a custom requestMiddleware list drops the default), and WORKOS_API_KEY optional.
  • 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 through this.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() and import.meta.glob neither 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-based createRoute({ 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 .server file 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 by iso().handler(h) ships h.

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 __root cache group: unblocked now that the Rspack panic (rspack#16289) is fixed.
  • Rsbuild dev source-map text: drop the post-hash .map fill 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.full server scenario renders its error page and vue-start.full an 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 normalizeRspackClientBuild runs 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: /ethos hangs in 6 of 12 runs here and 4 of 12 on eb12efe304, with no import-protection activity in those logs. Not checked on main.
    • Solid serialization-adapters stream: 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 at 17e475671e). 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 (allowImport follows the same order, documented), and CSS url() of a denied file on Rsbuild builds a silent mock. With source.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 · ✅ #229 import X = ns.Y · ✅ #230 decorators after export · ✅ #231 JSXText entities · ✅ #232 false duplicate export · ✅ #237 empty JSX container comments · ✅ #244 WASM stale bytes · ✅ #247 unwrap typing · ✅ #248 copyAst() · ✅ #251 export {} from · ✅ #252 import() specifiers · ✅ #253 big-endian decoding · ✅ #254 JSX attribute mapping · ✅ #255 postfix ++ parens · ✅ #256 for (init;;) no-in · ✅ #257 private method overloads · ✅ #258 import type {} · ✅ #259 super() in computed key · ✅ #260 JSX text after </> · ✅ #287 (a?.b)!.c · ✅ #288 JSXText escaping · ✅ #289 stale JSXText raw · ✖ #290 strip keeps type-only exports · ✅ #291 surrogate-pair spans · ✅ #292 Annex B functions · ✅ #318 export namespace A.B in file.exports

  • Vite:

  • Rolldown:

    • ○ #11054 this.load() returns null in bundled-dev HMR
    • ○ #11223 stale moduleSideEffects in watch mode
    • ○ #11300 bundled-dev MissingFactoryError
    • ✅ #11341 a helper in a dynamic chunk causes an entry cycle (#8139)
  • Rspack:

    • ○ #16288 HMR runs a module before its async chunk loads
    • ✅ #16289 splitChunks panic
    • ○ #16347 a missing sourcesContent entry is emitted as "", not null
    • ○ #16348 feature: fill missing sourcesContent from the module resource at map emission
  • Rsbuild:

    • ✅ #8736 the dev FS keeps hot-update files (fixed in Rsbuild 2.3.0)
  • solid-refresh (all ○):

    • #88 rename invalidate loop
    • #89 sticky first registry
    • #90 stale importer after a rename
    • #91 document remount (#6331)
    • #92 recursing proxies
  • Others:

Issues

Other issues:

  • #8437, partially addressed: Start's footer follows quoteStyle/semicolons, but tsr generate still 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: true on ssr.

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.

  1. Core: start with router-utils/src/compiler/README.md, then read identity → source/analysis → units/mutation → rewrite → reach → plan → emit → values/summary/facts → cache/pipeline → verify. Keep tests/helpers.ts and tests/placement.test.ts open alongside.
  2. Planners:
    • Router: router-plugin/ARCHITECTURE-CODE-SPLITTING.md, then src/planners/.
    • Start: start-plugin-core/src/planners/ (start-env, hydrate, rsc-css, edges), with src/compiler/, src/server-fns/ and src/import-protection/. Builder escapes: ESCAPE_MESSAGES in start-env.ts and tests/planners/start-builder-shapes.test.ts.
  3. Hosts:
    • router-plugin/src/hosts/.
    • Start's src/vite/compiler-plugin.ts.
    • Start's src/rsbuild/ (read COMPILER_ARCHITECTURE.md first).
  4. Generator and runtime:
    • router-generator (AGENTS.md, analyze/, model/, print/).
    • router-core/src/hmr.ts and {react,solid,vue}-router/src/hmr.ts.
    • start-client-core/src/createServerFn.ts.
  5. Tests: the oracle's README.md, SPEC.md and KNOWN-BUGS.md.

To reproduce the measurements, see:

  • packages/compiler-test-utils/oracle/README.md
  • benchmarks/compiler-perf/README.md (run.mjs, compare.mjs, soak-analyze.mjs)
  • pnpm benchmark:bundle-size:run
  • scripts/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. Important

      Draft PR not reviewed

      Draft PRs are not automatically reviewed by default.

      • Trigger a manual review

      To automatically review draft PRs, update your CodeRabbit configuration:

      reviews:
        auto_review:
          drafts: true
      • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

      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
    2. 🦋 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
      NameType
      @tanstack/start-plugin-coreMinor
      @tanstack/react-startMinor
      @tanstack/solid-startMinor
      @tanstack/vue-startMinor
      @tanstack/react-start-rscMinor
      @tanstack/router-utilsMinor
      @tanstack/router-pluginMinor
      @tanstack/router-generatorMinor
      @tanstack/router-cliPatch
      @tanstack/router-corePatch
      @tanstack/react-routerPatch
      @tanstack/solid-routerPatch
      @tanstack/vue-routerPatch
      @tanstack/router-vite-pluginPatch
      @tanstack/react-start-clientPatch
      @tanstack/react-start-serverPatch
      @tanstack/solid-start-clientPatch
      @tanstack/solid-start-serverPatch
      @tanstack/start-client-corePatch
      @tanstack/start-server-corePatch
      @tanstack/start-storage-contextPatch
      @tanstack/vue-start-clientPatch
      @tanstack/vue-start-serverPatch
      @tanstack/start-static-server-functionsPatch

      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

    3. github-actions[bot](GitHub profile, opens in a new tab) added labelsdocumentation

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

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

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

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

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

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

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

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

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

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

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

    15. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: react-start-rsc

    16. 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 priority
      Low adoption: npm @yuku-toolchain/darwin-arm64

      Location: 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 priority
      Low adoption: npm @yuku-toolchain/darwin-x64

      Location: 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 priority
      Low adoption: npm @yuku-toolchain/linux-arm64

      Location: 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 priority
      Low adoption: npm @yuku-toolchain/win32-arm64

      Location: 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 priority
      Low adoption: npm @yuku-toolchain/win32-x64

      Location: 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 full report

    17. View your CI Pipeline Execution ↗ for commit eb1a7841bb09858cf5a609e426596d8c012de762

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

      ☁️ Nx Cloud last updated this comment at 2026-11-04 06:03:43 UTC

    18. 🚀 Changeset Version Preview

      15 package(s) bumped directly, 9 bumped as dependents.

      🟨 Minor bumps

      PackageVersionReason
      @tanstack/react-start1.169.4 → 1.170.0Changeset
      @tanstack/react-start-rsc0.1.65 → 0.2.0Changeset
      @tanstack/router-cli1.167.46 → 1.168.0Changeset
      @tanstack/router-core1.171.39 → 1.172.0Changeset
      @tanstack/router-generator1.167.46 → 1.168.0Changeset
      @tanstack/router-plugin1.168.48 → 1.169.0Changeset
      @tanstack/router-utils1.162.4 → 1.163.0Changeset
      @tanstack/solid-start1.169.4 → 1.170.0Changeset
      @tanstack/start-plugin-core1.171.55 → 1.172.0Changeset
      @tanstack/vue-start1.169.4 → 1.170.0Changeset

      🟩 Patch bumps

      PackageVersionReason
      @tanstack/react-router1.170.46 → 1.170.47Changeset
      @tanstack/react-start-client1.168.44 → 1.168.45Changeset
      @tanstack/solid-router1.170.43 → 1.170.44Changeset
      @tanstack/start-client-core1.170.39 → 1.170.40Changeset
      @tanstack/vue-router1.170.42 → 1.170.43Changeset
      @tanstack/react-start-server1.167.52 → 1.167.53Dependent
      @tanstack/router-vite-plugin1.167.48 → 1.167.49Dependent
      @tanstack/solid-start-client1.168.42 → 1.168.43Dependent
      @tanstack/solid-start-server1.167.50 → 1.167.51Dependent
      @tanstack/start-server-core1.169.45 → 1.169.46Dependent
      @tanstack/start-static-server-functions1.167.44 → 1.167.45Dependent
      @tanstack/start-storage-context1.167.41 → 1.167.42Dependent
      @tanstack/vue-start-client1.167.45 → 1.167.46Dependent
      @tanstack/vue-start-server1.167.50 → 1.167.51Dependent
    19. 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:

      ScenarioCurrent (gzip)Initial (gzip)RawBrotliTrend
      react-start.full99.8&nbsp;KiB
      -52&nbsp;B
      99.7&nbsp;KiB
      -52&nbsp;B
      311.6&nbsp;KiB
      -48&nbsp;B
      86.6&nbsp;KiB
      +86&nbsp;B
      ███████████▁
      react-start.rsbuild.minimal100.3&nbsp;KiB
      -8&nbsp;B
      100.2&nbsp;KiB
      -9&nbsp;B
      313.2&nbsp;KiB
      -22&nbsp;B
      86.6&nbsp;KiB
      -1&nbsp;B
      ▁▁▁▁▁▁▁▁▁▁█▂
      react-start.rsbuild.minimal-iife100.8&nbsp;KiB
      -11&nbsp;B
      100.6&nbsp;KiB
      -12&nbsp;B
      314.2&nbsp;KiB
      -22&nbsp;B
      87.0&nbsp;KiB
      -2&nbsp;B
      ▁▁▁▁▁▁▁▁▁▁█▃
      react-start.rsbuild.full103.5&nbsp;KiB
      -45&nbsp;B
      103.3&nbsp;KiB
      -46&nbsp;B
      322.9&nbsp;KiB
      -62&nbsp;B
      89.3&nbsp;KiB
      +72&nbsp;B
      ▇▇▇▇▇▇▇▇▇▇█▁
      solid-start.full51.1&nbsp;KiB
      -42&nbsp;B
      51.0&nbsp;KiB
      -44&nbsp;B
      150.0&nbsp;KiB
      -48&nbsp;B
      45.4&nbsp;KiB
      -104&nbsp;B
      ███████████▁
      vue-start.full69.1&nbsp;KiB
      -42&nbsp;B
      68.9&nbsp;KiB
      -43&nbsp;B
      197.5&nbsp;KiB
      -48&nbsp;B
      61.6&nbsp;KiB
      -24&nbsp;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.

    20. 🤖 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):

      appbuild real / floor / oursdev cold → / hydrateddev compile-all
      react-start1,634 / 779 / 8552,561 / 1,581 / 9802,038 / 1,055 / 983
      react-router612 / 419 / 1931,046 / 856 / 1901,303 / 996 / 307
      solid-start4,375 / 3,283 / 1,0923,406 / 2,348 / 1,0584,624 / 3,693 / 931
      solid-router1,982 / 1,875 / 1071,490 / 1,317 / 1734,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, made edgeKey/canonicalJson cheaper, ran hit validation in parallel and skipped emission for identity outputs. Re-profile before picking the next own-code target. Sync time in our transform hooks is ~200 ms; the rest runs after awaits, mostly resolutions.

      Dev startup

      1. 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 and import() 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/client statically, 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.

      2. 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 resolveId settles 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/paths covers 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.

      3. 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.

      4. Pre-bundle Start's late dependencies. seroval, seroval-plugins/web and cookie-es are 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 client optimizeDeps.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.

      5. 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

      1. 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.

      2. 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 reading file.imports[].local: modules that never reach tier 1 no longer build the node→index map, so re-measure the gain before filing.

      3. 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 dependencyPaths on the plan.
        • Drop the facts deep clone in freeze().

        Honest total ≤ 50–100 ms; re-profile first.

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

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

      6. The generator's configResolved runs 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 in EmitPlan (−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), so const 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 and new 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+b modules and export~Name forwarders cost one request each; a route-aware advancedChunks hint trades requests, not bytes. Nothing else material.

    21. More templates

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

      commit: eb1a784

    22. Merging 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.

      Learn more about system calls

      See affected benchmarks

      :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

      See affected benchmarks

      :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.

      See affected benchmarks

      ⚡ 1 improved benchmark ❌ 1 (👁 1) regressed benchmark ✅ 192 untouched benchmarks ⏩ 3 skipped benchmarks1

      Performance Changes

      ModeBenchmarkBASEHEADEfficiency
      👁Memorymem client interrupted-navigations (solid)83.8 KB86.9 KB-3.53%
      👁Memorymem client navigation-churn (solid)112.8 KB105.6 KB+6.81%

      Tip

      Curious why performance improved? Comment @codspeedbot explain why performance improved on this PR, or directly use the CodSpeed MCP with your agent.


      Comparing compiler-rewrite/yuku (eb1a784) with main (da8c28c) Open in CodSpeed

      Footnotes

      1. 3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

    23. 🤖 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

      1. 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.
      2. 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 Link preloads, per-route modulepreload/early hints, fewer waterfalls.
      3. 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
      4. 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.
      5. 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).
      6. 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.ts files and leaks.

      Also enabled

      Compiler APIs

      • ssr: false route code pruned from server output → placement decides per output; the route model needs each file's ssr option and its inheritance → M → no server evaluation of browser-only modules.
      • Split head/scripts (awaited after loaders, like a split loader) → a new split key is a declared root → S each. validateSearch/params schemas 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 Link checks (unknown routes, missing params) for JS projects and dynamic strings → route model + Link recognisable 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 compile CLI over a directory → S → debugging, codemods.

      Maintenance: React/Solid/Vue share every planner, so features reach all three at once.

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

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

    26. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: react-start-client

Sign in to join this conversation.