Skip to content
Source
Sign inSign up
TanStack/router

feat: report unsupported compiler patterns instead of skipping them (prototype) #8642

OpenSheraff(GitHub profile, opens in a new tab)wants to merge 10 commits intocodex/yuku-evaluation fromfeat/compiler-diagnosticsopened

Prototype, stacked on #8504 (Babel → Yuku compiler migration). It captures diagnostics for compiler patterns that are already silent on main, so they are not forgotten. Patterns that became silent in the migration itself are handled in #8504 (for example the this.warn for a route created inside a function, which this PR reuses).

Policy agreed with the maintainer:

  • Failing beats leaking silently.
  • Warn in dev, error in build, so an edit in progress does not break the dev server. Security leaks (server code shipped to the client) fail the build and are loud in dev.
  • Precedent: import protection ({ dev, build } behaviour, dedup with a seen set, bundler warning channel).

Breadth over polish: each item has behaviour-level tests in its topic suite, but the messages, option surface and exact precision are open for discussion (see the open questions).

Items

#PatternBefore: main / #8504NowDev / buildRelated #8630 pin
1Any Start factory call the compiler missed (cross-module included): createServerFn().handler() without the compiled RPC, createServerOnlyFn(), createClientOnlyFn(), createIsomorphicFn().server() reaching the runtime stub in the browsersilent: server code runs in / ships to the browserconsole.error naming the factory, that it was not compiled, and how to write it (module-level variable, factory imported directly from the Start package)dev, browser only (NODE_ENV !== 'production' && !== 'test', !(isServer ?? typeof window === 'undefined')) / nothing in productionruntime safety net for the cross-module pins: export * diamonds/cycles, builder finished in another module, namespace-read builder (F.authed.handler), re-exported Start namespace, authed() from another module
2Unrecognized use of a Start factory in the client compilation: const authed = () => createServerFn(), (0, createServerFn)(), Start['createServerFn'](), aliased createServerOnlyFn inside a function, builder in an object property or a ternary, factory passed to user codesilent: implementation and its server-only imports ship to the clientUnrecognized use of createX at file:line:col: it is not compiled, so its implementation ships to the client. …this.warn once per message / build errorflips "a builder returned by a function of the same module"; now reported (pin stays red because it asserts compilation): "createServerOnlyFn called through a renamed import / local alias in a function body", "result is member-called (.bind)"
3Two createFileRoute calls in one route filemain: renders the wrong component; #8504: build fails with "Duplicated export 'component'""file" calls createFileRoute 2 times: + file:line:col of each callerror in dev and build (output would be broken either way); a root route next to a file route is fine—
4aawait / for await / yield in split <Hydrate> children (outside nested functions)chunk does not parse, unclear build failureclear compile errorerror (dev and build)flips "await in split children is rejected clearly"
4barguments of the component in split children (stops at non-arrow functions)chunk silently reads its own propsclear compile errorerrorflips "split children reading the component's arguments"
4cHooks recognized by binding: useState as st, React 19 use(), React.useId() (namespace or default import; react, solid-js, vue), plus the existing use[A-Z0-9] name rule for custom hooksmoved into the chunk componentexisting "calls hooks during render" errorerrorflips "a hook called through a namespace in the children is rejected"
4d<Hydrate {...props} />: children from a spread, left unsplitsilent"receives its children from a spread, so they won't be code-split"dev warning only / nothingrelated to "children passed through a spread" (still red: it asserts they render split)
5"These exports … will not be code-split"console.warn on every transform; missing in a production build when the exported option is the only split onebundler this.warn, once per message, also in buildswarn / warn—
6aSplit option written as a method, getter or setter (component() {})silently not split"… is a method, so it will not be code-split. Write it as a property: component: () => ..." (#8459 proposes splitting them instead)warn / warn—
6b['codeSplitGroupings'] computed keysilently ignorederrorerror / error—
6cSplit options or codeSplitGroupings from a spread resolving to an object literal; split option behind a computed key ['component']silently not split / ignoredwarning naming the keyswarn / warn—
6dcreateFileRoute<'/a'>('/a') (type arguments)route file skipped by the code filter: not split, not hot-updatedfix: filter accepts \s*(?:<|\() for every route factory——
6eimport { createFileRoute as cfr }, Router.createFileRoute(...) in a route filesilently neither split nor hot-updatedwarning from the code splitter and the route HMR pluginwarn / warnrelated to the generator pin "a moved route with an aliased import gets the id of its new path" (still red, generator not touched)
7Disallowed character in square brackets of a route pathconsole.error + process.exit(1): kills the dev serverthrows; the generator plugin logs it in dev and keeps running; a build now fails on any route generation error (Vite command === 'build', Rspack/webpack beforeRun) instead of bundling a stale treelog / error—

Pin status was checked by running the known-bugs-start-compiler and known-bugs-hydrate files of #8630 against this branch and against #8504: exactly the four pins named "flips" above change from expected-fail to passing. The router-plugin and router-generator pins were not affected by design.

Notes per item

  • 1: the runtime check fires once per definition (module evaluation), so it needs no dedup. createIsomorphicFn() alone is not reported, since compiled code keeps a bare builder (export const iso = createIsomorphicFn()); only .server() reaching the stub is. start-fn-stubs uses typeof window !== 'undefined' without isServer, to avoid adding a @tanstack/router-core dependency to it; the NODE_ENV gate already removes the block from every production bundle, and isServer is undefined in dev, so it would not change any outcome. start-client-core uses isServer ?? typeof window === 'undefined' as AGENTS.md says. NODE_ENV === 'test' is excluded explicitly because unit tests (Vitest with jsdom) run uncompiled by design.
  • 2: references come from Yuku (module.imports, binding.references, parentOf), not names. A reference is accepted when it is on a call chain the compiler rewrote, initializes a module-level variable with an unfinished builder (no .handler/.server/.client/.createMiddlewares in the chain, createServerFn/createMiddleware/createIsomorphicFn only), or initializes a module-level alias (const cs = createServerFn) whose references follow the same rule. Of the rest, only uses that call the factory (through any call/member chain, sequence, conditional or logical expression) or pass it to a function are reported; other value uses (an array element, an object value, a comparison, a re-export, a type) carry no implementation and are left alone. That last rule came from the bundle-size benchmark app react-start.full, whose [createMiddleware, createServerFn, useServerFn] failed its build with the first version. References inside code the client output drops (server fn handler, middleware/isomorphic .server() argument, createServerOnlyFn argument) are skipped. Only the client compilation checks, and virtual modules (?tss-…) are skipped so a Hydrate chunk does not report twice.
  • 5: the injected dev-only console.warn in the route module stays: it reaches the browser console, where the terminal warning is often not seen. Note that Vite 8 relays browser console output to the terminal, so in dev the terminal now shows the bundler warning once per environment (client and SSR) plus a relayed [console.warn] per page load; dropping the injected warning is an option if that is too noisy. Dedup is per message (which names the file and exports), so an edit that changes the exported set reports again.
  • 6: option checks only run for keys the effective groupings would split (a loader() {} with the default groupings is not reported).

False positives / precision

  • 2 — factory passed to user code (makeBuilder(createServerFn)): reported. The compiler cannot follow it either way, so the implementation does ship, but a user may consider it intentional.
  • 2 — build errors ignore tree-shaking: unlike import protection, a build fails even if the unrecognized use is dead code (an unused const authed = () => createServerFn()). Reporting only what survives tree-shaking would need the import-protection deferral machinery.
  • 2 — dependencies are compiled too: a library that wraps a Start factory in one of these patterns now fails the user's build (same as #8504's createServerFn placement error).
  • 2 — escaping value uses are not reported: const factories = { cs: createServerFn }; factories.cs().handler(...) leaks without a compile-time report (item 1 catches it at runtime in dev). This is the price of not failing on the benchmark-style [createServerFn] surface arrays.
  • 2 — gaps: aliasing a namespace (const S = Start; S.createServerFn()), an alias declared with destructuring, and cross-module patterns (a builder in another module) are not reported at compile time; item 1 catches the cross-module ones at runtime in dev.
  • 1 — Storybook / uncompiled browser dev environments: a story that imports a module defining a server fn logs one console.error per server fn (the statement is true, the server code is in that bundle, but it is harmless there). Vitest is excluded via NODE_ENV=test; Vitest browser mode with another NODE_ENV is not.
  • 4c: the name rule (use[A-Z0-9]…) is kept for custom hooks, so a non-hook function named useThing is still rejected, as before.
  • 4d: a spread of a non-literal object always warns, even if it never holds children.
  • 6c: only spreads of a module-level object literal are resolved; an imported object is not.
  • 7: a build that hit any generator error (not only this one) used to log and continue with a stale route tree; it now fails.

Open questions for the maintainer

  1. Should an unrecognized factory use be a dev overlay error (like import protection's error mode) rather than a terminal warning, given it is a server-code leak?
  2. Add a user option mirroring import protection, e.g. compilerDiagnostics: { dev: 'warn' | 'error' | 'off', build: … }, at least to silence item 2 for libraries / intentional patterns?
  3. Item 2 in builds: fail at transform time (current), or report only uses that survive tree-shaking (import-protection style, more machinery)?
  4. Item 1: should it also throw (not only console.error) for createServerOnlyFn, so the leaked server code does not run in the browser in dev? And is excluding NODE_ENV=test acceptable given AGENTS.md's !== 'production' rule?
  5. Item 3 is an error in dev too, since the output is broken either way. OK, or warn in dev and keep only the first route?
  6. Item 7: should a generator error fail the build for every error (current), or only for this one?

Validation

  • test:unit (Nx): router-plugin 973, router-utils 84, router-generator 270 + 12, start-plugin-core 925, start-client-core 125, start-fn-stubs 18, react-start-rsc 67 (affected consumer): all pass.
  • test:types, test:eslint, test:build for router-plugin, router-utils, router-generator, start-plugin-core, start-client-core, start-fn-stubs: pass (start-client-core keeps its 44 existing lint warnings).
  • tanstack-router-e2e-react-basic-file-based-code-splitting:test:e2e: 6 passed. One new-channel warning in the build output, a true positive: posts.$postId.tsx exports PostErrorComponent, used as its errorComponent ("will not be code-split", item 5). It was already printed with console.warn before.
  • tanstack-react-start-e2e-basic:test:e2e: all modes pass (137–140 tests each). No new message in the build or test output.
  • Dev smoke test of e2e/react-start/server-functions (vite dev, Playwright: /, /env-only, /isomorphic-fns, /server-fn-in-client-only-fn, running the env-only and isomorphic functions): no [TanStack Start] runtime report and no compile-time report, so the internal createServerOnlyFn/createIsomorphicFn().server() uses of start-client-core are compiled in dev and do not trigger item 1.
  • Bundle size (benchmark:bundle-size:run, all 18 scenarios, #8504 head 37111c76a7 vs this branch), production gzip bytes, all unchanged (raw, brotli and initial also +0):
ScenarioBaseThis PRΔ
react-router.minimal85979859790
react-router.full89627896270
solid-router.minimal34285342850
solid-router.full39322393220
vue-router.minimal50647506470
vue-router.full56396563960
react-start.minimal99029990290
react-start.query-integration1066541066540
react-start.deferred-hydration99773997730
react-start.full1022851022850
react-start.rsbuild.minimal1027351027350
react-start.rsbuild.minimal-iife1031541031540
react-start.rsbuild.full1060621060620
solid-start.minimal47358473580
solid-start.deferred-hydration50476504760
solid-start.full52614526140
vue-start.minimal67003670030
vue-start.full70939709390

The benchmark builds print none of the new diagnostics. Only the measurement phase of the bundle-size workflow was run: there is nothing to optimize at +0.

  • #8630 pins: see the table (4 pins flip; none regress).

🤖 Generated with Claude Code

    1. 🦋 Changeset detected

      Latest commit: a618e3b341a71982f9d33f4d37f8a2ebdf851c58

      The changes in this PR will be included in the next version bump.

      This PR includes changesets to release 19 packages
      NameType
      @tanstack/router-pluginMinor
      @tanstack/router-generatorPatch
      @tanstack/start-plugin-coreMinor
      @tanstack/start-client-corePatch
      @tanstack/start-fn-stubsPatch
      @tanstack/router-vite-pluginPatch
      @tanstack/router-cliPatch
      @tanstack/react-start-rscPatch
      @tanstack/react-startPatch
      @tanstack/solid-startPatch
      @tanstack/vue-startPatch
      @tanstack/react-start-clientPatch
      @tanstack/solid-start-clientPatch
      @tanstack/start-server-corePatch
      @tanstack/start-static-server-functionsPatch
      @tanstack/vue-start-clientPatch
      @tanstack/react-start-serverPatch
      @tanstack/solid-start-serverPatch
      @tanstack/vue-start-serverPatch

      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

    2. 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
      • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

      Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

      ❤️ Share
      Comment `@coderabbitai help` to get the list of available commands.
    3. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-plugin

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

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

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

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

    8. View your CI Pipeline Execution ↗ for commit a618e3b341a71982f9d33f4d37f8a2ebdf851c58

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

      ☁️ Nx Cloud last updated this comment at 2026-10-08 21:07:21 UTC

    9. 🚀 Changeset Version Preview

      14 package(s) bumped directly, 12 bumped as dependents.

      🟨 Minor bumps

      PackageVersionReason
      @tanstack/router-cli1.167.40 → 1.168.0Changeset
      @tanstack/router-generator1.167.40 → 1.168.0Changeset
      @tanstack/router-plugin1.168.42 → 1.169.0Changeset
      @tanstack/router-utils1.162.3 → 1.163.0Changeset
      @tanstack/router-vite-plugin1.167.42 → 1.168.0Changeset
      @tanstack/start-plugin-core1.171.49 → 1.172.0Changeset

      🟩 Patch bumps

      PackageVersionReason
      @tanstack/history1.162.4 → 1.162.5Changeset
      @tanstack/react-router1.170.41 → 1.170.42Changeset
      @tanstack/react-start-rsc0.1.59 → 0.1.60Changeset
      @tanstack/router-core1.171.34 → 1.171.35Changeset
      @tanstack/solid-router1.170.38 → 1.170.39Changeset
      @tanstack/start-client-core1.170.34 → 1.170.35Changeset
      @tanstack/start-fn-stubs1.162.0 → 1.162.1Changeset
      @tanstack/vue-router1.170.37 → 1.170.38Changeset
      @tanstack/react-start1.168.60 → 1.168.61Dependent
      @tanstack/react-start-client1.168.39 → 1.168.40Dependent
      @tanstack/react-start-server1.167.46 → 1.167.47Dependent
      @tanstack/solid-start1.168.57 → 1.168.58Dependent
      @tanstack/solid-start-client1.168.37 → 1.168.38Dependent
      @tanstack/solid-start-server1.167.44 → 1.167.45Dependent
      @tanstack/start-server-core1.169.39 → 1.169.40Dependent
      @tanstack/start-static-server-functions1.167.39 → 1.167.40Dependent
      @tanstack/start-storage-context1.167.36 → 1.167.37Dependent
      @tanstack/vue-start1.168.56 → 1.168.57Dependent
      @tanstack/vue-start-client1.167.40 → 1.167.41Dependent
      @tanstack/vue-start-server1.167.44 → 1.167.45Dependent
    10. Bundle Size Benchmarks

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

    11. More templates

      @tanstack/arktype-adapter

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

      @tanstack/eslint-plugin-router

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

      @tanstack/eslint-plugin-start

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

      @tanstack/history

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

      @tanstack/nitro-v2-vite-plugin

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

      @tanstack/react-router

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

      @tanstack/react-router-devtools

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

      @tanstack/react-router-ssr-query

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

      @tanstack/react-start

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

      @tanstack/react-start-client

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

      @tanstack/react-start-rsc

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

      @tanstack/react-start-server

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

      @tanstack/router-cli

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

      @tanstack/router-core

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

      @tanstack/router-devtools

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

      @tanstack/router-devtools-core

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

      @tanstack/router-generator

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

      @tanstack/router-plugin

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

      @tanstack/router-ssr-query-core

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

      @tanstack/router-utils

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

      @tanstack/router-vite-plugin

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

      @tanstack/solid-router

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

      @tanstack/solid-router-devtools

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

      @tanstack/solid-router-ssr-query

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

      @tanstack/solid-start

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

      @tanstack/solid-start-client

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

      @tanstack/solid-start-server

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

      @tanstack/start-client-core

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

      @tanstack/start-fn-stubs

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

      @tanstack/start-plugin-core

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

      @tanstack/start-server-core

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

      @tanstack/start-static-server-functions

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

      @tanstack/start-storage-context

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

      @tanstack/valibot-adapter

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

      @tanstack/virtual-file-routes

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

      @tanstack/vue-router

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

      @tanstack/vue-router-devtools

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

      @tanstack/vue-router-ssr-query

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

      @tanstack/vue-start

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

      @tanstack/vue-start-client

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

      @tanstack/vue-start-server

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

      @tanstack/zod-adapter

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

      commit: a618e3b

    12. Merging this PR will not alter performance

      ✅ 194 untouched benchmarks ⏩ 3 skipped benchmarks1


      Comparing feat/compiler-diagnostics (a618e3b) with codex/yuku-evaluation (37111c7) Open in CodSpeed

      Footnotes

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

Sign in to join this conversation.