feat(react-router): publish router state as concurrent render frames

.changeset/concurrent-router-render-frames.md

@@ -0,0 +1,10 @@
+---
+'@tanstack/react-router': minor
+'@tanstack/router-core': minor
+---
+
+Add an experimental `experimental_concurrentRenderFrames` router option that publishes router state to React as one immutable render frame per navigation.
+
+React's `<ViewTransition>` and other transition-only behaviour never engage across a navigation today, because router state reaches components through `useSyncExternalStore`, which React schedules at a synchronous lane from the store's own subscription callback — after the `startTransition` scope has exited. When enabled, the React adapter owns the committed frame in state, stages a successor inside the transition, and acknowledges the exact rendered frame, so an interrupted or superseded navigation cannot settle a newer one.
+
+Default off; with the option unset, the existing granular store subscriptions and selector behaviour are unchanged.

.github/workflows/bundle-size.yml

@@ -45,7 +45,7 @@ jobs:
         uses: TanStack/config/.github/setup@e4b48f16568324f76f467aa4c2aac2f05db632c3 # main
 
       - name: Measure Bundle Size
-        run: pnpm nx run @benchmarks/bundle-size:build --outputStyle=stream --skipRemoteCache
+        run: pnpm benchmark:bundle-size --outputStyle=stream --skipRemoteCache
 
       - name: Capture Benchmark Outputs
         id: capture
@@ -127,7 +127,7 @@ jobs:
         uses: TanStack/config/.github/setup@e4b48f16568324f76f467aa4c2aac2f05db632c3 # main
 
       - name: Measure Bundle Size
-        run: pnpm nx run @benchmarks/bundle-size:build --outputStyle=stream --skipRemoteCache
+        run: pnpm benchmark:bundle-size --outputStyle=stream --skipRemoteCache
       - name: Publish Benchmark Dashboard
         uses: benchmark-action/github-action-benchmark@52576c92bccf6ac60c8223ec7eb2565637cae9ba # v1.22.1
         with:

.gitignore

@@ -66,6 +66,7 @@ nx-cloud.env
 .nx/workspace-data
 .nx/polygraph
 .nx/self-healing
+.nx/migrate-runs
 
 gpt/db.json
 

benchmarks/bundle-size/README.md

@@ -40,7 +40,9 @@ pnpm benchmark:bundle-size:run --scenario react-router.minimal,react-router.full
 ```
 
 The runner calls `measure.mjs`, which builds the selected package projects through Nx. Full runs build the package projects for all scenarios.
-The existing `pnpm benchmark:bundle-size` command keeps its CI build graph unchanged.
+`pnpm benchmark:bundle-size` uses the Nx build cache for the full benchmark, then generates `current.json` with the current commit, branch, dirty status, and report timestamp. CI uses this command as well.
+
+Nx caches the bundles, `measurements.json`, and `benchmark-action.json`. Git metadata does not affect the build cache. The report preserves the original `measuredAt` and build duration when measurements come from cache; `generatedAt` records when the report was generated. Running `pnpm nx run @benchmarks/bundle-size:build` directly produces only the cacheable outputs; run `node scripts/benchmarks/bundle-size/report.mjs` afterward to refresh `current.json`.
 
 If the required packages are already built and unchanged, skip that step:
 
@@ -50,6 +52,7 @@ pnpm benchmark:bundle-size:run --scenario react-router.minimal --skip-package-bu
 
 This writes:
 
+- `benchmarks/bundle-size/results/measurements.json`
 - `benchmarks/bundle-size/results/current.json`
 - `benchmarks/bundle-size/results/benchmark-action.json`
 - `benchmarks/bundle-size/results/measure.log`

benchmarks/bundle-size/package.json

@@ -3,13 +3,27 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "build": "node ../../scripts/benchmarks/bundle-size/measure.mjs --skip-package-builds",
-    "test:unit": "node --test ../../scripts/benchmarks/bundle-size/pr-report.test.mjs ../../scripts/benchmarks/bundle-size/run.test.mjs"
+    "build": "node ../../scripts/benchmarks/bundle-size/measure.mjs --skip-package-builds --measurements-only",
+    "test:unit": "node --test ../../scripts/benchmarks/bundle-size/pr-report.test.mjs ../../scripts/benchmarks/bundle-size/run.test.mjs ../../scripts/benchmarks/bundle-size/report.test.mjs ../../scripts/benchmarks/bundle-size/build.test.mjs"
   },
   "nx": {
     "targets": {
       "build": {
-        "cache": false,
+        "inputs": [
+          "buildProduction",
+          "^buildProduction",
+          "dependentTaskOutputs",
+          "{workspaceRoot}/scripts/benchmarks/bundle-size/measure.mjs",
+          "{workspaceRoot}/scripts/benchmarks/bundle-size/report.mjs",
+          {
+            "runtime": "node --version"
+          }
+        ],
+        "outputs": [
+          "{projectRoot}/dist",
+          "{projectRoot}/results/measurements.json",
+          "{projectRoot}/results/benchmark-action.json"
+        ],
         "dependsOn": [
           {
             "projects": [

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

@@ -1,3 +1,4 @@
+import { defineComponent } from 'vue'
 import {
   Asset,
   Await,
@@ -45,143 +46,151 @@ import {
   useTags,
 } from '@tanstack/vue-router'
 
-export const Route = createRootRoute({
-  component: RootComponent,
-})
+const RootComponent = defineComponent({
+  setup() {
+    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()
 
-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()
+    useBlocker({
+      shouldBlockFn: () => false,
+      disabled: true,
+      withResolver: false,
+    })
 
-  useBlocker({
-    shouldBlockFn: () => false,
-    disabled: true,
-    withResolver: false,
-  })
+    const linkFactoryResult = linkOptions({ to: '/' } as any)
+    const routeMatchResult = matchRoute({ to: '/' } as any)
+    const SvgLink = createLink('svg')
 
-  const linkFactoryResult = linkOptions({ to: '/' } as any)
-  const routeMatchResult = matchRoute({ to: '/' } as any)
-  const SvgLink = createLink('svg')
+    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,
+    ]
 
-  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,
+    }
 
-  ;(globalThis as any).__TANSTACK_BUNDLE_SIZE_KEEP__ = {
-    hooksAndComponents,
-  }
+    return () => {
+      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 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
+      return (
+        <>
+          <HeadContent />
+          <ScriptOnce>{'window.__tsr_bundle_size = true'}</ScriptOnce>
+          <Asset
+            tag="meta"
+            attrs={{ name: 'bundle-size', content: 'vue-router-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>
+        </>
+      )
+    }
+  },
+})
 
-  return (
-    <>
-      <HeadContent />
-      <ScriptOnce>{'window.__tsr_bundle_size = true'}</ScriptOnce>
-      <Asset
-        tag="meta"
-        attrs={{ name: 'bundle-size', content: 'vue-router-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>
-    </>
-  )
-}
+export const Route = createRootRoute({
+  component: RootComponent,
+})