perf(router-plugin): write dev snippets as typed templates compiled into AST builders at build time #8684
perf/direct-builders-pr fromproto/hmr-typed-templates·opened 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'svite.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 React | webpack React | Vite Solid | Dev 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.hotrather thanimport.meta.hot. TypeScript can't scope anImportMetaaugmentation to some files of a program. A TypeScript project-reference setup works, but it needstsc -b, serial type checks across TS versions and changes to the d.ts build, which costs more than it saves. handleRouteUpdateis 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
github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-plugin
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.
Comment `@coderabbitai help` to get the list of available commands.View your CI Pipeline Execution ↗ for commit 726ce29253a58109ecfd9c54177f32b45ceb0370
Command Status Duration Result nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded 15m 23s View ↗ nx run-many --target=build --exclude=examples/*...✅ Succeeded 54s View ↗
☁️ Nx Cloud last updated this comment at
2026-10-12 07:35:20UTC🚀 Changeset Version Preview#
7 package(s) bumped directly, 3 bumped as dependents.
🟨 Minor bumps#
Package Version Reason @tanstack/router-cli1.167.41 → 1.168.0 Changeset @tanstack/router-generator1.167.41 → 1.168.0 Changeset @tanstack/router-plugin1.168.43 → 1.169.0 Changeset @tanstack/router-utils1.162.3 → 1.163.0 Changeset @tanstack/router-vite-plugin1.167.43 → 1.168.0 Changeset @tanstack/start-plugin-core1.171.50 → 1.172.0 Changeset 🟩 Patch bumps#
Package Version Reason @tanstack/react-start-rsc0.1.60 → 0.1.61 Changeset @tanstack/react-start1.168.61 → 1.168.62 Dependent @tanstack/solid-start1.168.58 → 1.168.59 Dependent @tanstack/vue-start1.168.57 → 1.168.58 Dependent Bundle Size Benchmarks#
This pull request does not affect bundle size in any measured scenario.
More templates
- tanstack-router-react-example-authenticated-routes
- tanstack-router-react-example-authenticated-routes-firebase
- tanstack-router-react-example-basic
- tanstack-router-react-example-basic-default-search-params
- tanstack-router-react-example-basic-devtools-panel
- tanstack-router-react-example-basic-file-based
- tanstack-router-react-example-basic-non-nested-devtools
- tanstack-router-react-example-react-query
- tanstack-router-react-example-basic-react-query-file-based
- tanstack-router-react-example-basic-ssr-file-based
- tanstack-router-react-example-basic-ssr-streaming-file-based
- tanstack-router-react-example-basic-virtual-file-based
- tanstack-router-react-example-basic-virtual-inside-file-based
- tanstack-router-react-example-deferred-data
- tanstack-router-i18n-paraglide
- tanstack-router-react-example-kitchen-sink
- tanstack-router-react-example-kitchen-sink-file-based
- tanstack-router-react-example-kitchen-sink-react-query
- tanstack-router-react-example-kitchen-sink-react-query-file-based
- tanstack-router-react-example-large-file-based
- tanstack-router-react-example-location-masking
- tanstack-router-react-example-navigation-blocking
- tanstack-router-react-example-quickstart
- tanstack-router-react-example-quickstart-esbuild-file-based
- tanstack-router-react-example-quickstart-file-based
- tanstack-router-react-example-quickstart-rspack-file-based
- tanstack-router-react-example-quickstart-webpack-file-based
- router-monorepo-react-query
- router-mono-simple
- router-mono-simple-lazy
- tanstack-router-react-example-scroll-restoration
- tanstack-search-validator-adapters
- tanstack-start-example-bare
- tanstack-start-example-basic
- tanstack-start-example-basic-auth
- tanstack-router-react-example-basic-authjs
- tanstack-start-example-basic-cloudflare
- tanstack-start-example-basic-react-query
- tanstack-start-example-basic-rsbuild
- tanstack-start-example-basic-static
- tanstack-start-bun-hosting
- tanstack-start-example-clerk-basic
- tanstack-start-example-convex-trellaux
- tanstack-start-example-counter
- tanstack-start-i18n-paraglide
- tanstack-start-example-large
- tanstack-start-example-material-ui
- tanstack-start-example-next-migration
- tanstack-start-example-rscs
- tanstack-start-streaming-data-from-server-functions
- tanstack-start-example-supabase-basic
- tanstack-start-tailwind-v4
- tanstack-start-example-trellaux
- tanstack-start-example-workos
- tanstack-router-react-example-view-transitions
- tanstack-router-react-example-with-framer-motion
- tanstack-router-react-example-with-trpc
- tanstack-router-react-example-with-trpc-react-query
- tanstack-router-solid-example-authenticated-routes
- tanstack-router-solid-example-authenticated-routes-firebase
- tanstack-router-solid-example-basic
- tanstack-router-solid-example-basic-default-search-params
- tanstack-router-solid-example-basic-devtools-panel
- tanstack-router-solid-example-basic-file-based
- tanstack-router-solid-example-basic-non-nested-devtools
- tanstack-router-solid-example-basic-solid-query
- tanstack-router-solid-example-basic-solid-query-file-based
- tanstack-router-solid-example-basic-ssr-file-based
- tanstack-router-solid-example-basic-ssr-streaming-file-based
- tanstack-router-solid-example-basic-virtual-file-based
- tanstack-router-solid-example-basic-virtual-inside-file-based
- tanstack-router-solid-example-deferred-data
- tanstack-router-solid-i18n-paraglide
- tanstack-router-solid-example-kitchen-sink
- tanstack-router-solid-example-kitchen-sink-file-based
- tanstack-router-solid-example-kitchen-sink-solid-query
- tanstack-router-solid-example-kitchen-sink-solid-query-file-based
- tanstack-router-solid-example-large-file-based
- tanstack-router-solid-example-location-masking
- tanstack-router-solid-example-navigation-blocking
- tanstack-router-solid-example-quickstart
- tanstack-router-solid-example-quickstart-esbuild-file-based
- tanstack-router-solid-example-quickstart-file-based
- tanstack-router-solid-example-quickstart-rspack-file-based
- tanstack-router-solid-example-quickstart-webpack-file-based
- @tanstack/router-solid-mono-simple
- router-solid-mono-simple-lazy
- router-solid-monorepo-solid-query
- tanstack-router-solid-example-scroll-restoration
- tanstack-solid-router-search-validator-adapters
- tanstack-solid-start-example-basic
- tanstack-solid-start-example-basic-auth
- tanstack-solid-start-example-basic-authjs
- tanstack-solid-start-example-basic-cloudflare
- tanstack-solid-start-example-basic-netlify
- tanstack-solid-start-example-basic-nitro
- tanstack-start-example-basic-solid-query
- tanstack-solid-start-example-basic-static
- tanstack-solid-start-bun-hosting
- tanstack-solid-start-example-convex-better-auth
- tanstack-solid-start-example-counter
- tanstack-solid-start-i18n-paraglide
- tanstack-solid-start-example-large
- tanstack-solid-start-streaming-data-from-server-functions
- tanstack-solid-start-example-supabase-basic
- tanstack-solid-start-tailwind-v4
- tanstack-router-solid-example-view-transitions
- tanstack-router-solid-example-with-framer-motion
- tanstack-router-solid-example-with-trpc
- tanstack-router-vue-example-basic-jsx
- tanstack-router-vue-example-basic-file-based-jsx
- tanstack-router-vue-example-basic-file-based-sfc
@tanstack/arktype-adapter
npm i https://pkg.pr.new/@tanstack/arktype-adapter@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@8684commit:
726ce29Merging this PR will regress 1 benchmark#
⚡ 1improved benchmark❌ 1regressed benchmark✅ 192untouched benchmarks⏩ 3skipped benchmarks1Warning
Please fix the performance issues or acknowledge them on CodSpeed.
Performance Changes#
Mode Benchmark BASEHEADEfficiency ❌ Memory mem client navigation-churn (solid)95 KB 98.1 KB -3.23% ⚡ Memory mem server aborted-requests (vue)104.1 KB 100.6 KB +3.49% Tip
Investigate this regression by commenting
@codspeedbot fix this regressionon this PR, or directly use the CodSpeed MCP with your agent.
Comparingproto/hmr-typed-templates(726ce29) withperf/direct-builders-pr(b119fd7)Footnotes#
-
3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩
-
Sign in to join this conversation.
🦋 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
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