Skip to content
Source
Sign inSign up
TanStack/router

perf(router-plugin): write dev snippets as typed templates compiled into AST builders at build time #8684

OpenSheraff(GitHub profile, opens in a new tab)wants to merge 7 commits intoperf/direct-builders-pr fromproto/hmr-typed-templatesopened

Stacked on #8680. Draft: a checkpoint of a new approach.

The router plugin inserts fixed code into route modules in dev: the Vite and webpack route HMR blocks, handleRouteUpdate, and the React Refresh snippets. Today these are strings, apart from handleRouteUpdate, which is toString()-ed. They are parsed on every transform.

This PR writes each snippet as real, type-checked TypeScript. At package build time, and under Vitest, a small Vite plugin compiles each one into the yuku-ast builder calls a person would write by hand, so a route transform never parses it.

const viteRouteHmr = astTemplate(
  {
    handleRouteUpdateFunction: hole.expression<HandleRouteUpdate>(),
    routeIdFallback: hole.expression<string | undefined>(),
  },
  ({ handleRouteUpdateFunction, routeIdFallback }) => {
    if (importMeta.hot) {
      const hot = importMeta.hot
      // …
    }
  },
)

viteRouteHmr({ handleRouteUpdateFunction: createHandleRouteUpdate(keys), routeIdFallback: literal(routeId) })

builds into

var viteRouteHmr = (holes) => [b.IfStatement({
  test: b.MemberExpression({ object: b.MetaProperty({ … }), property: b.Identifier({ name: "hot" }), … }),
  consequent: b.BlockStatement({ body: [ … init: holes.handleRouteUpdateFunction … ] }),
  • Typed holes. Inside a template, a hole has the type of the runtime value it stands for. The builder accepts what the compiler passes: an expression, an identifier name, a literal value, or statements. Other free names belong to the route module and are declared in the template module, e.g. declare const Route: AnyRoute.
  • Build-time checks. An unknown or unused hole, or unsupported syntax, fails the build and Vitest with a code frame pointing at the template.
  • Plugin wiring. The plugin (packages/router-plugin/ast-templates-plugin.ts) is registered in the package's vite.config.ts, so the ESM and CJS builds and Vitest all run the same compiled code. It reprints modules with Yuku's printer, source maps included. It adds no dependency, and no generated file needs to be committed.
  • Output. It differs from #8680 in three ways: template comments and redundant parentheses are no longer emitted, and the HMR snippets are simplified without changing what they do.

Performance

Medians of 10 alternating pairs, measured one at a time, vs #8680:

Vite Reactwebpack ReactVite SolidDev transforms, 250 routes
Hand-written builders (reference, not in this PR)−29%−26%−24%−5.6%
This PR−30%−28%−23%−5.6%

Inserted dev code per HMR route module: 3,571 → 3,332 B (Vite React), 2,949 → 2,635 B (webpack React), 2,417 → 2,243 B (Vite Solid). The compiler drops template comments and redundant parentheses (the printer re-adds the ones precedence needs), and the HMR snippets were simplified without changing what they do.

Notes

  • Templates write importMeta.hot rather than import.meta.hot. TypeScript can't scope an ImportMeta augmentation to some files of a program. A TypeScript project-reference setup works, but it needs tsc -b, serial type checks across TS versions and changes to the d.ts build, which costs more than it saves.
  • handleRouteUpdate is inserted from its source instead of the bundler's re-printed form, so tests and published code agree.

Written with Claude Code (AI-assisted).

✅ Checklist

  • I have followed the steps in the Contributing guide.
  • I have tested code changes locally with the relevant test commands, or tests do not apply to this pull request.
  • I fully understand the code in this pull request, including any code generated with AI assistance.

🚀 Release Impact

  • This change affects published code, and I have generated a changeset.
  • This change is docs/CI/dev-only (no release).

🤖 Generated with Claude Code

    1. 🦋 Changeset detected

      Latest commit: 726ce29253a58109ecfd9c54177f32b45ceb0370

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

      This PR includes changesets to release 7 packages
      NameType
      @tanstack/router-pluginPatch
      @tanstack/router-vite-pluginPatch
      @tanstack/start-plugin-corePatch
      @tanstack/react-start-rscPatch
      @tanstack/react-startPatch
      @tanstack/solid-startPatch
      @tanstack/vue-startPatch

      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. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-plugin

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

      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.
    4. View your CI Pipeline Execution ↗ for commit 726ce29253a58109ecfd9c54177f32b45ceb0370

      CommandStatusDurationResult
      nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded15m 23sView ↗
      nx run-many --target=build --exclude=examples/*...✅ Succeeded54sView ↗

      ☁️ Nx Cloud last updated this comment at 2026-10-12 07:35:20 UTC

    5. 🚀 Changeset Version Preview

      7 package(s) bumped directly, 3 bumped as dependents.

      🟨 Minor bumps

      PackageVersionReason
      @tanstack/router-cli1.167.41 → 1.168.0Changeset
      @tanstack/router-generator1.167.41 → 1.168.0Changeset
      @tanstack/router-plugin1.168.43 → 1.169.0Changeset
      @tanstack/router-utils1.162.3 → 1.163.0Changeset
      @tanstack/router-vite-plugin1.167.43 → 1.168.0Changeset
      @tanstack/start-plugin-core1.171.50 → 1.172.0Changeset

      🟩 Patch bumps

      PackageVersionReason
      @tanstack/react-start-rsc0.1.60 → 0.1.61Changeset
      @tanstack/react-start1.168.61 → 1.168.62Dependent
      @tanstack/solid-start1.168.58 → 1.168.59Dependent
      @tanstack/vue-start1.168.57 → 1.168.58Dependent
    6. Bundle Size Benchmarks

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

    7. More templates

      @tanstack/arktype-adapter

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

      @tanstack/eslint-plugin-router

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

      @tanstack/eslint-plugin-start

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

      @tanstack/history

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

      @tanstack/nitro-v2-vite-plugin

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

      @tanstack/react-router

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

      @tanstack/react-router-devtools

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

      @tanstack/react-router-ssr-query

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

      @tanstack/react-start

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

      @tanstack/react-start-client

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

      @tanstack/react-start-rsc

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

      @tanstack/react-start-server

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

      @tanstack/router-cli

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

      @tanstack/router-core

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

      @tanstack/router-devtools

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

      @tanstack/router-devtools-core

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

      @tanstack/router-generator

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

      @tanstack/router-plugin

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

      @tanstack/router-ssr-query-core

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

      @tanstack/router-utils

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

      @tanstack/router-vite-plugin

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

      @tanstack/solid-router

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

      @tanstack/solid-router-devtools

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

      @tanstack/solid-router-ssr-query

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

      @tanstack/solid-start

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

      @tanstack/solid-start-client

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

      @tanstack/solid-start-server

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

      @tanstack/start-client-core

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

      @tanstack/start-fn-stubs

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

      @tanstack/start-plugin-core

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

      @tanstack/start-server-core

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

      @tanstack/start-static-server-functions

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

      @tanstack/start-storage-context

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

      @tanstack/valibot-adapter

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

      @tanstack/virtual-file-routes

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

      @tanstack/vue-router

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

      @tanstack/vue-router-devtools

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

      @tanstack/vue-router-ssr-query

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

      @tanstack/vue-start

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

      @tanstack/vue-start-client

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

      @tanstack/vue-start-server

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

      @tanstack/zod-adapter

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

      commit: 726ce29

    8. Merging this PR will regress 1 benchmark

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

      Warning

      Please fix the performance issues or acknowledge them on CodSpeed.

      Performance Changes

      ModeBenchmarkBASEHEADEfficiency
      ❌Memorymem client navigation-churn (solid)95 KB98.1 KB-3.23%
      ⚡Memorymem server aborted-requests (vue)104.1 KB100.6 KB+3.49%

      Tip

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


      Comparing proto/hmr-typed-templates (726ce29) with perf/direct-builders-pr (b119fd7) 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.