improve bundle size benchmarks and add initial skill

.agents/skills/bundle-size-optimization

@@ -0,0 +1 @@
+../../skills/bundle-size-optimization

AGENTS.md

@@ -21,6 +21,7 @@ TanStack Router is a type-safe router with built-in caching and URL state manage
 - Framework-agnostic core logic separated from React/Solid bindings
 - Type-safe routing with search params and path params
 - Use workspace protocol for internal dependencies (`workspace:*`)
+- Always use curly braces for `if`, `else`, loops, and similar control statements. Never write one-line bodies like `if (foo) x = 1`.
 
 ## Dev environment tips
 

benchmarks/bundle-size/README.md

@@ -32,11 +32,41 @@ Each package has `minimal` and `full` scenarios:
 pnpm nx run @benchmarks/bundle-size:build
 ```
 
+Run one or more scenarios during local optimization:
+
+```bash
+pnpm nx run @benchmarks/bundle-size:build -- --scenario react-router.minimal
+pnpm nx run @benchmarks/bundle-size:build -- --scenario react-router.minimal,react-router.full
+```
+
+Filtered runs build only the package projects needed by selected scenarios. Full runs build all package projects needed by all scenarios. If the required packages are already built and unchanged, skip that step:
+
+```bash
+pnpm nx run @benchmarks/bundle-size:build -- --scenario react-router.minimal --skip-package-builds
+```
+
 This writes:
 
 - `benchmarks/bundle-size/results/current.json`
 - `benchmarks/bundle-size/results/benchmark-action.json`
 
+`current.json` includes run status, selected package build projects, per-scenario totals, per-file sizes, and the emitted JS files used for measurement. Dist paths use `scenarioDir`/`outDir`, e.g. `react-router.minimal` maps to `benchmarks/bundle-size/dist/react-router-minimal/`.
+
+## Local Query Tools
+
+```bash
+pnpm benchmark:bundle-size:query --id react-router.minimal
+pnpm benchmark:bundle-size:diff --baseline /tmp/base-current.json --id react-router.minimal
+pnpm benchmark:bundle-size:history --id react-router.minimal --top-deltas 20
+```
+
+For source attribution, run an analysis build. This uses hidden source maps and writes source estimates into `current.json`; those estimates are for investigation only, not tracking.
+
+```bash
+pnpm nx run @benchmarks/bundle-size:build -- --scenario react-router.minimal --analysis
+pnpm benchmark:bundle-size:analyze --id react-router.minimal --top-sources 30
+```
+
 ## CI Reporting
 
 - PR workflow generates a sticky comment with:
@@ -56,6 +86,10 @@ The measurement script supports optional interfaces for historical backfilling:
 - `--sha`
 - `--measured-at`
 - `--append-history`
+- `--scenario`
+- `--analysis`
+- `--sourcemap`
+- `--skip-package-builds`
 
 These are intended for one-off scripts that replay historical commits and append results to the same history dataset shape used for chart generation.
 If `--append-history` points at a `data.js` file, output is written as `window.BENCHMARK_DATA = ...` for direct GitHub Pages compatibility.

benchmarks/bundle-size/package.json

@@ -5,12 +5,21 @@
   "scripts": {
     "build": "node ../../scripts/benchmarks/bundle-size/measure.mjs"
   },
+  "nx": {
+    "targets": {
+      "build": {
+        "cache": false,
+        "dependsOn": []
+      }
+    }
+  },
   "dependencies": {
     "@tanstack/react-router": "workspace:^",
     "@tanstack/solid-router": "workspace:^",
     "@tanstack/vue-router": "workspace:^",
     "@tanstack/react-start": "workspace:^",
     "@tanstack/solid-start": "workspace:^",
+    "@tanstack/vue-start": "workspace:^",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "solid-js": "^1.9.10",

benchmarks/bundle-size/scenarios/react-start-minimal/rsbuild.config.ts

@@ -3,10 +3,20 @@ import { pluginReact } from '@rsbuild/plugin-react'
 import { tanstackStart } from '@tanstack/react-start/plugin/rsbuild'
 
 const outDir = process.env.BUNDLE_SIZE_DIST_DIR ?? 'dist-rsbuild'
+const clientOutput = process.env.BUNDLE_SIZE_RSB_CLIENT_OUTPUT
+const startOptions = clientOutput
+  ? {
+      rsbuild: {
+        client: {
+          output: clientOutput as 'module' | 'iife',
+        },
+      },
+    }
+  : undefined
 
 export default defineConfig({
   logLevel: 'silent',
-  plugins: [pluginReact({ splitChunks: false }), tanstackStart()],
+  plugins: [pluginReact({ splitChunks: false }), tanstackStart(startOptions)],
   output: {
     distPath: {
       root: outDir,

benchmarks/bundle-size/scenarios/vue-start-full/src/router.tsx

@@ -0,0 +1,9 @@
+import { createRouter } from '@tanstack/vue-router'
+import { routeTree } from './routeTree.gen'
+
+export function getRouter() {
+  return createRouter({
+    routeTree,
+    scrollRestoration: true,
+  })
+}

benchmarks/bundle-size/scenarios/vue-start-full/src/routes/__root.tsx

@@ -0,0 +1,218 @@
+import {
+  Asset,
+  Await,
+  Block,
+  Body,
+  CatchBoundary,
+  CatchNotFound,
+  ClientOnly,
+  DefaultGlobalNotFound,
+  ErrorComponent,
+  HeadContent,
+  Html,
+  Link,
+  Match,
+  MatchRoute,
+  Matches,
+  Navigate,
+  Outlet,
+  RouterContextProvider,
+  ScriptOnce,
+  Scripts,
+  ScrollRestoration,
+  createLink,
+  createRootRoute,
+  linkOptions,
+  useAwaited,
+  useBlocker,
+  useCanGoBack,
+  useChildMatches,
+  useElementScrollRestoration,
+  useLinkProps,
+  useLoaderData,
+  useLoaderDeps,
+  useLocation,
+  useMatch,
+  useMatchRoute,
+  useMatches,
+  useNavigate,
+  useParams,
+  useParentMatches,
+  useRouteContext,
+  useRouter,
+  useRouterState,
+  useSearch,
+  useTags,
+} from '@tanstack/vue-router'
+import {
+  createMiddleware,
+  createServerFn,
+  useServerFn,
+} from '@tanstack/vue-start'
+
+const requestMiddleware = createMiddleware().server(async ({ next }) => {
+  return next()
+})
+
+const functionMiddleware = createMiddleware({ type: 'function' })
+  .client(async ({ next }) => {
+    return next()
+  })
+  .server(async ({ next }) => {
+    return next()
+  })
+
+const helloServerFn = createServerFn({ method: 'GET' })
+  .middleware([requestMiddleware, functionMiddleware])
+  .handler(async () => {
+    return 'hello from server fn'
+  })
+
+export const Route = createRootRoute({
+  component: RootComponent,
+})
+
+function RootComponent() {
+  const router = useRouter()
+  const [awaited] = useAwaited({ promise: Promise.resolve('ready') })
+  const linkProps = useLinkProps({ to: '/' } as any)
+  const matchRoute = useMatchRoute()
+  const matches = useMatches()
+  const parentMatches = useParentMatches()
+  const childMatches = useChildMatches()
+  const match = useMatch({ strict: false, shouldThrow: false } as any)
+  const loaderDeps = useLoaderDeps({ strict: false } as any)
+  const loaderData = useLoaderData({ strict: false } as any)
+  const params = useParams({ strict: false } as any)
+  const search = useSearch({ strict: false } as any)
+  const routeContext = useRouteContext({ strict: false } as any)
+  const routerState = useRouterState({ select: (state) => state.status } as any)
+  const location = useLocation()
+  const canGoBack = useCanGoBack()
+  const navigate = useNavigate()
+  const scrollEntry = useElementScrollRestoration({ id: 'root-scroll' })
+  const tags = useTags()
+  const invokeServerFn = useServerFn(helloServerFn)
+
+  useBlocker({
+    shouldBlockFn: () => false,
+    disabled: true,
+    withResolver: false,
+  })
+
+  const linkFactoryResult = linkOptions({ to: '/' } as any)
+  const routeMatchResult = matchRoute({ to: '/' } as any)
+  const SvgLink = createLink('svg')
+
+  const startSurface = [createMiddleware, createServerFn, useServerFn]
+  const hooksAndComponents = [
+    useAwaited,
+    useLinkProps,
+    useMatchRoute,
+    useMatches,
+    useParentMatches,
+    useChildMatches,
+    useMatch,
+    useLoaderDeps,
+    useLoaderData,
+    useBlocker,
+    useNavigate,
+    useParams,
+    useSearch,
+    useRouteContext,
+    useRouter,
+    useRouterState,
+    useLocation,
+    useCanGoBack,
+    useElementScrollRestoration,
+    useTags,
+    Await,
+    CatchBoundary,
+    CatchNotFound,
+    ClientOnly,
+    DefaultGlobalNotFound,
+    ErrorComponent,
+    Link,
+    Match,
+    MatchRoute,
+    Matches,
+    Navigate,
+    Outlet,
+    RouterContextProvider,
+    ScrollRestoration,
+    Block,
+    ScriptOnce,
+    Asset,
+    HeadContent,
+    Scripts,
+    Body,
+    Html,
+  ]
+
+  ;(globalThis as any).__TANSTACK_BUNDLE_SIZE_KEEP__ = {
+    hooksAndComponents,
+    startSurface,
+  }
+
+  void awaited
+  void linkFactoryResult
+  void matches.value
+  void parentMatches.value
+  void childMatches.value
+  void match.value
+  void loaderDeps.value
+  void loaderData.value
+  void params.value
+  void search.value
+  void routeContext.value
+  void routerState.value
+  void location.value
+  void canGoBack.value
+  void navigate
+  void scrollEntry
+  void tags()
+  void routeMatchResult.value
+  void invokeServerFn
+
+  return (
+    <Html>
+      <head>
+        <HeadContent />
+      </head>
+      <Body>
+        <ScriptOnce>{'window.__tsr_bundle_size = true'}</ScriptOnce>
+        <Asset
+          tag="meta"
+          attrs={{ name: 'bundle-size', content: 'vue-start-full' }}
+        />
+        <Link {...(linkProps as any)}>home</Link>
+        <SvgLink to="/" aria-label="svg-home">
+          <circle cx="8" cy="8" r="7" />
+        </SvgLink>
+        <MatchRoute to="/">{() => <span data-test="match-route" />}</MatchRoute>
+        <ClientOnly fallback={<span data-test="client-only-fallback" />}>
+          <span data-test="client-only" />
+        </ClientOnly>
+        <Await
+          promise={Promise.resolve('done')}
+          children={() => <span data-test="await" />}
+        />
+        <Block shouldBlockFn={() => false} disabled withResolver={false}>
+          {() => <span data-test="block" />}
+        </Block>
+        <CatchNotFound fallback={() => <DefaultGlobalNotFound />}>
+          <span data-test="catch-not-found" />
+        </CatchNotFound>
+        <RouterContextProvider router={router}>
+          <span data-test="nested-router-context" />
+        </RouterContextProvider>
+        <ScrollRestoration />
+        <Outlet />
+        <Scripts />
+        <div data-test="full-root">
+          <div>hello world</div>
+        </div>
+      </Body>
+    </Html>
+  )
+}

benchmarks/bundle-size/scenarios/vue-start-full/src/routes/index.tsx

@@ -0,0 +1,9 @@
+import { createFileRoute } from '@tanstack/vue-router'
+
+export const Route = createFileRoute('/')({
+  component: IndexComponent,
+})
+
+function IndexComponent() {
+  return <div>hello world</div>
+}

benchmarks/bundle-size/scenarios/vue-start-full/vite.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import vueJsx from '@vitejs/plugin-vue-jsx'
+import { tanstackStart } from '@tanstack/vue-start/plugin/vite'
+
+export default defineConfig({
+  plugins: [tanstackStart(), vue(), vueJsx()],
+})

benchmarks/bundle-size/scenarios/vue-start-minimal/src/router.tsx

@@ -0,0 +1,9 @@
+import { createRouter } from '@tanstack/vue-router'
+import { routeTree } from './routeTree.gen'
+
+export function getRouter() {
+  return createRouter({
+    routeTree,
+    scrollRestoration: true,
+  })
+}

benchmarks/bundle-size/scenarios/vue-start-minimal/src/routes/__root.tsx

@@ -0,0 +1,26 @@
+import {
+  Body,
+  HeadContent,
+  Html,
+  Outlet,
+  Scripts,
+  createRootRoute,
+} from '@tanstack/vue-router'
+
+export const Route = createRootRoute({
+  component: RootComponent,
+})
+
+function RootComponent() {
+  return (
+    <Html>
+      <head>
+        <HeadContent />
+      </head>
+      <Body>
+        <Outlet />
+        <Scripts />
+      </Body>
+    </Html>
+  )
+}