@tanstack/react-router 1.167.5 → 1.168.1

package/dist/llms/rules/api.js

@@ -1841,7 +1841,6 @@ type RouterState = {
   isLoading: boolean
   isTransitioning: boolean
   matches: Array<RouteMatch>
-  pendingMatches: Array<RouteMatch>
   location: ParsedLocation
   resolvedLocation: ParsedLocation
 }
@@ -1871,11 +1870,6 @@ The \`RouterState\` type contains all of the properties that are available on th
 - Type: [\`Array<RouteMatch>\`](./RouteMatchType.md)
 - An array of all of the route matches that have been resolved and are currently active.
 
-### \`pendingMatches\` property
-
-- Type: [\`Array<RouteMatch>\`](./RouteMatchType.md)
-- An array of all of the route matches that are currently pending.
-
 ### \`location\` property
 
 - Type: [\`ParsedLocation\`](./ParsedLocationType.md)
@@ -3797,7 +3791,7 @@ function Component() {
 The \`useChildMatches\` hook returns all of the child [\`RouteMatch\`](./RouteMatchType.md) objects from the closest match down to the leaf-most match. **It does not include the current match, which can be obtained using the \`useMatch\` hook.**
 
 > [!IMPORTANT]
-> If the router has pending matches and they are showing their pending component fallbacks, \`router.state.pendingMatches\` will used instead of \`router.state.matches\`.
+> If the router has pending matches and they are showing their pending component fallbacks, pending matches are used instead of active matches.
 
 ## useChildMatches options
 
@@ -4406,7 +4400,7 @@ function Component() {
 The \`useParentMatches\` hook returns all of the parent [\`RouteMatch\`](./RouteMatchType.md) objects from the root down to the immediate parent of the current match in context. **It does not include the current match, which can be obtained using the \`useMatch\` hook.**
 
 > [!IMPORTANT]
-> If the router has pending matches and they are showing their pending component fallbacks, \`router.state.pendingMatches\` will used instead of \`router.state.matches\`.
+> If the router has pending matches and they are showing their pending component fallbacks, pending matches are used instead of active matches.
 
 ## useParentMatches options
 
@@ -4514,7 +4508,7 @@ function Component() {
 The \`useRouterState\` method is a hook that returns the current internal state of the router. This hook is useful for accessing the current state of the router in a component.
 
 > [!TIP]
-> If you want to access the current location or the current matches, you should try out the [\`useLocation\`](./useLocationHook.md) and [\`useMatches\`](./useMatchesHook.md) hooks first. These hooks are designed to be more ergonomic and easier to use than accessing the router state directly.
+> If you want to access the current location or the current matches, you should try out the [\`useLocation\`](./useLocationHook.md) and [\`useMatches\`](./useMatchesHook.md) hooks first. These hooks are designed to be more performant, more ergonomic and easier to use than accessing the router state directly.
 
 ## useRouterState options
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-router",
-  "version": "1.167.5",
+  "version": "1.168.1",
   "description": "Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -77,12 +77,12 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@tanstack/react-store": "^0.9.1",
+    "@tanstack/react-store": "^0.9.2",
     "isbot": "^5.1.22",
     "tiny-invariant": "^1.3.3",
     "tiny-warning": "^1.0.3",
     "@tanstack/history": "1.161.6",
-    "@tanstack/router-core": "1.167.5"
+    "@tanstack/router-core": "1.168.1"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",

package/src/Match.tsx

@@ -1,4 +1,5 @@
 import * as React from 'react'
+import { useStore } from '@tanstack/react-store'
 import invariant from 'tiny-invariant'
 import warning from 'tiny-warning'
 import {
@@ -10,7 +11,6 @@ import {
 } from '@tanstack/router-core'
 import { isServer } from '@tanstack/router-core/isServer'
 import { CatchBoundary, ErrorComponent } from './CatchBoundary'
-import { useRouterState } from './useRouterState'
 import { useRouter } from './useRouter'
 import { CatchNotFound } from './not-found'
 import { matchContext } from './matchContext'
@@ -30,25 +30,88 @@ export const Match = React.memo(function MatchImpl({
   matchId: string
 }) {
   const router = useRouter()
-  const matchState = useRouterState({
-    select: (s) => {
-      const matchIndex = s.matches.findIndex((d) => d.id === matchId)
-      const match = s.matches[matchIndex]
-      invariant(
-        match,
-        `Could not find match for matchId "${matchId}". Please file an issue!`,
-      )
-      return {
-        routeId: match.routeId,
-        ssr: match.ssr,
-        _displayPending: match._displayPending,
-        resetKey: s.loadedAt,
-        parentRouteId: s.matches[matchIndex - 1]?.routeId as string,
-      }
-    },
-    structuralSharing: true as any,
-  })
 
+  if (isServer ?? router.isServer) {
+    const match = router.stores.activeMatchStoresById.get(matchId)?.state
+    invariant(
+      match,
+      `Could not find match for matchId "${matchId}". Please file an issue!`,
+    )
+
+    const routeId = match.routeId as string
+    const parentRouteId = (router.routesById[routeId] as AnyRoute).parentRoute
+      ?.id
+
+    return (
+      <MatchView
+        router={router}
+        matchId={matchId}
+        resetKey={router.stores.loadedAt.state}
+        matchState={{
+          routeId,
+          ssr: match.ssr,
+          _displayPending: match._displayPending,
+          parentRouteId,
+        }}
+      />
+    )
+  }
+
+  // Subscribe directly to the match store from the pool.
+  // The matchId prop is stable for this component's lifetime (set by Outlet),
+  // and reconcileMatchPool reuses stores for the same matchId.
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  const matchStore = router.stores.activeMatchStoresById.get(matchId)
+  invariant(
+    matchStore,
+    `Could not find match for matchId "${matchId}". Please file an issue!`,
+  )
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  const resetKey = useStore(router.stores.loadedAt, (loadedAt) => loadedAt)
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  const match = useStore(matchStore, (value) => value)
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  const matchState = React.useMemo(() => {
+    const routeId = match.routeId as string
+    const parentRouteId = (router.routesById[routeId] as AnyRoute).parentRoute
+      ?.id
+
+    return {
+      routeId,
+      ssr: match.ssr,
+      _displayPending: match._displayPending,
+      parentRouteId: parentRouteId as string | undefined,
+    } satisfies MatchViewState
+  }, [match._displayPending, match.routeId, match.ssr, router.routesById])
+
+  return (
+    <MatchView
+      router={router}
+      matchId={matchId}
+      resetKey={resetKey}
+      matchState={matchState}
+    />
+  )
+})
+
+type MatchViewState = {
+  routeId: string
+  ssr: boolean | 'data-only' | undefined
+  _displayPending: boolean | undefined
+  parentRouteId: string | undefined
+}
+
+function MatchView({
+  router,
+  matchId,
+  resetKey,
+  matchState,
+}: {
+  router: ReturnType<typeof useRouter>
+  matchId: string
+  resetKey: number
+  matchState: MatchViewState
+}) {
   const route: AnyRoute = router.routesById[matchState.routeId]
 
   const PendingComponent =
@@ -94,7 +157,7 @@ export const Match = React.memo(function MatchImpl({
       <matchContext.Provider value={matchId}>
         <ResolvedSuspenseBoundary fallback={pendingElement}>
           <ResolvedCatchBoundary
-            getResetKey={() => matchState.resetKey}
+            getResetKey={() => resetKey}
             errorComponent={routeErrorComponent || ErrorComponent}
             onCatch={(error, errorInfo) => {
               // Forward not found errors (we don't want to show the error component for these)
@@ -137,7 +200,7 @@ export const Match = React.memo(function MatchImpl({
       ) : null}
     </ShellComponent>
   )
-})
+}
 
 // On Rendered can't happen above the root layout because it actually
 // renders a dummy dom element to track the rendered state of the app.
@@ -165,7 +228,10 @@ function OnRendered() {
         ) {
           router.emit({
             type: 'onRendered',
-            ...getLocationChangeInfo(router.state),
+            ...getLocationChangeInfo(
+              router.stores.location.state,
+              router.stores.resolvedLocation.state,
+            ),
           })
           prevLocationRef.current = router.latestLocation
         }
@@ -181,39 +247,101 @@ export const MatchInner = React.memo(function MatchInnerImpl({
 }): any {
   const router = useRouter()
 
-  const { match, key, routeId } = useRouterState({
-    select: (s) => {
-      const match = s.matches.find((d) => d.id === matchId)!
-      const routeId = match.routeId as string
-
-      const remountFn =
-        (router.routesById[routeId] as AnyRoute).options.remountDeps ??
-        router.options.defaultRemountDeps
-      const remountDeps = remountFn?.({
-        routeId,
-        loaderDeps: match.loaderDeps,
-        params: match._strictParams,
-        search: match._strictSearch,
-      })
-      const key = remountDeps ? JSON.stringify(remountDeps) : undefined
-
-      return {
-        key,
-        routeId,
-        match: {
-          id: match.id,
-          status: match.status,
-          error: match.error,
-          _forcePending: match._forcePending,
-          _displayPending: match._displayPending,
-        },
-      }
-    },
-    structuralSharing: true as any,
-  })
+  if (isServer ?? router.isServer) {
+    const match = router.stores.activeMatchStoresById.get(matchId)?.state
+    invariant(
+      match,
+      `Could not find match for matchId "${matchId}". Please file an issue!`,
+    )
 
-  const route = router.routesById[routeId] as AnyRoute
+    const routeId = match.routeId as string
+    const route = router.routesById[routeId] as AnyRoute
+    const remountFn =
+      (router.routesById[routeId] as AnyRoute).options.remountDeps ??
+      router.options.defaultRemountDeps
+    const remountDeps = remountFn?.({
+      routeId,
+      loaderDeps: match.loaderDeps,
+      params: match._strictParams,
+      search: match._strictSearch,
+    })
+    const key = remountDeps ? JSON.stringify(remountDeps) : undefined
+    const Comp = route.options.component ?? router.options.defaultComponent
+    const out = Comp ? <Comp key={key} /> : <Outlet />
+
+    if (match._displayPending) {
+      throw router.getMatch(match.id)?._nonReactive.displayPendingPromise
+    }
 
+    if (match._forcePending) {
+      throw router.getMatch(match.id)?._nonReactive.minPendingPromise
+    }
+
+    if (match.status === 'pending') {
+      throw router.getMatch(match.id)?._nonReactive.loadPromise
+    }
+
+    if (match.status === 'notFound') {
+      invariant(isNotFound(match.error), 'Expected a notFound error')
+      return renderRouteNotFound(router, route, match.error)
+    }
+
+    if (match.status === 'redirected') {
+      invariant(isRedirect(match.error), 'Expected a redirect error')
+      throw router.getMatch(match.id)?._nonReactive.loadPromise
+    }
+
+    if (match.status === 'error') {
+      const RouteErrorComponent =
+        (route.options.errorComponent ??
+          router.options.defaultErrorComponent) ||
+        ErrorComponent
+      return (
+        <RouteErrorComponent
+          error={match.error as any}
+          reset={undefined as any}
+          info={{
+            componentStack: '',
+          }}
+        />
+      )
+    }
+
+    return out
+  }
+
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  const matchStore = router.stores.activeMatchStoresById.get(matchId)
+  invariant(
+    matchStore,
+    `Could not find match for matchId "${matchId}". Please file an issue!`,
+  )
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  const match = useStore(matchStore, (value) => value)
+  const routeId = match.routeId as string
+  const route = router.routesById[routeId] as AnyRoute
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  const key = React.useMemo(() => {
+    const remountFn =
+      (router.routesById[routeId] as AnyRoute).options.remountDeps ??
+      router.options.defaultRemountDeps
+    const remountDeps = remountFn?.({
+      routeId,
+      loaderDeps: match.loaderDeps,
+      params: match._strictParams,
+      search: match._strictSearch,
+    })
+    return remountDeps ? JSON.stringify(remountDeps) : undefined
+  }, [
+    routeId,
+    match.loaderDeps,
+    match._strictParams,
+    match._strictSearch,
+    router.options.defaultRemountDeps,
+    router.routesById,
+  ])
+
+  // eslint-disable-next-line react-hooks/rules-of-hooks
   const out = React.useMemo(() => {
     const Comp = route.options.component ?? router.options.defaultComponent
     if (Comp) {
@@ -309,37 +437,49 @@ export const MatchInner = React.memo(function MatchInnerImpl({
 export const Outlet = React.memo(function OutletImpl() {
   const router = useRouter()
   const matchId = React.useContext(matchContext)
-  const routeId = useRouterState({
-    select: (s) => s.matches.find((d) => d.id === matchId)?.routeId as string,
-  })
-
-  const route = router.routesById[routeId]!
-
-  const parentGlobalNotFound = useRouterState({
-    select: (s) => {
-      const matches = s.matches
-      const parentMatch = matches.find((d) => d.id === matchId)
-      invariant(
-        parentMatch,
-        `Could not find parent match for matchId "${matchId}"`,
-      )
-      return parentMatch.globalNotFound
-    },
-  })
-
-  const childMatchId = useRouterState({
-    select: (s) => {
-      const matches = s.matches
-      const index = matches.findIndex((d) => d.id === matchId)
-      return matches[index + 1]?.id
-    },
-  })
+
+  let routeId: string | undefined
+  let parentGlobalNotFound = false
+  let childMatchId: string | undefined
+
+  if (isServer ?? router.isServer) {
+    const matches = router.stores.activeMatchesSnapshot.state
+    const parentIndex = matchId
+      ? matches.findIndex((match) => match.id === matchId)
+      : -1
+    const parentMatch = parentIndex >= 0 ? matches[parentIndex] : undefined
+    routeId = parentMatch?.routeId as string | undefined
+    parentGlobalNotFound = parentMatch?.globalNotFound ?? false
+    childMatchId =
+      parentIndex >= 0 ? (matches[parentIndex + 1]?.id as string) : undefined
+  } else {
+    // Subscribe directly to the match store from the pool instead of
+    // the two-level byId → matchStore pattern.
+    const parentMatchStore = matchId
+      ? router.stores.activeMatchStoresById.get(matchId)
+      : undefined
+
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    ;[routeId, parentGlobalNotFound] = useStore(parentMatchStore, (match) => [
+      match?.routeId as string | undefined,
+      match?.globalNotFound ?? false,
+    ])
+
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    childMatchId = useStore(router.stores.matchesId, (ids) => {
+      const index = ids.findIndex((id) => id === matchId)
+      return ids[index + 1]
+    })
+  }
+
+  const route = routeId ? router.routesById[routeId] : undefined
 
   const pendingElement = router.options.defaultPendingComponent ? (
     <router.options.defaultPendingComponent />
   ) : null
 
   if (parentGlobalNotFound) {
+    invariant(route, 'Could not resolve route for Outlet render')
     return renderRouteNotFound(router, route, undefined)
   }
 

package/src/Matches.tsx

@@ -1,9 +1,9 @@
 import * as React from 'react'
 import warning from 'tiny-warning'
-import { rootRouteId } from '@tanstack/router-core'
+import { useStore } from '@tanstack/react-store'
+import { replaceEqualDeep, rootRouteId } from '@tanstack/router-core'
 import { isServer } from '@tanstack/router-core/isServer'
 import { CatchBoundary, ErrorComponent } from './CatchBoundary'
-import { useRouterState } from './useRouterState'
 import { useRouter } from './useRouter'
 import { Transitioner } from './Transitioner'
 import { matchContext } from './matchContext'
@@ -28,7 +28,6 @@ import type {
   ResolveRelativePath,
   ResolveRoute,
   RouteByPath,
-  RouterState,
   ToSubOptionsProps,
 } from '@tanstack/router-core'
 
@@ -78,15 +77,15 @@ export function Matches() {
 
 function MatchesInner() {
   const router = useRouter()
-  const matchId = useRouterState({
-    select: (s) => {
-      return s.matches[0]?.id
-    },
-  })
-
-  const resetKey = useRouterState({
-    select: (s) => s.loadedAt,
-  })
+  const _isServer = isServer ?? router.isServer
+  const matchId = _isServer
+    ? router.stores.firstMatchId.state
+    : // eslint-disable-next-line react-hooks/rules-of-hooks
+      useStore(router.stores.firstMatchId, (id) => id)
+  const resetKey = _isServer
+    ? router.stores.loadedAt.state
+    : // eslint-disable-next-line react-hooks/rules-of-hooks
+      useStore(router.stores.loadedAt, (loadedAt) => loadedAt)
 
   const matchComponent = matchId ? <Match matchId={matchId} /> : null
 
@@ -144,10 +143,10 @@ export type UseMatchRouteOptions<
 export function useMatchRoute<TRouter extends AnyRouter = RegisteredRouter>() {
   const router = useRouter()
 
-  useRouterState({
-    select: (s) => [s.location.href, s.resolvedLocation?.href, s.status],
-    structuralSharing: true as any,
-  })
+  if (!(isServer ?? router.isServer)) {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useStore(router.stores.matchRouteReactivity, (d) => d)
+  }
 
   return React.useCallback(
     <
@@ -238,15 +237,36 @@ export function useMatches<
   opts?: UseMatchesBaseOptions<TRouter, TSelected, TStructuralSharing> &
     StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
 ): UseMatchesResult<TRouter, TSelected> {
-  return useRouterState({
-    select: (state: RouterState<TRouter['routeTree']>) => {
-      const matches = state.matches
-      return opts?.select
-        ? opts.select(matches as Array<MakeRouteMatchUnion<TRouter>>)
-        : matches
-    },
-    structuralSharing: opts?.structuralSharing,
-  } as any) as UseMatchesResult<TRouter, TSelected>
+  const router = useRouter<TRouter>()
+  const previousResult =
+    React.useRef<ValidateSelected<TRouter, TSelected, TStructuralSharing>>(
+      undefined,
+    )
+
+  if (isServer ?? router.isServer) {
+    const matches = router.stores.activeMatchesSnapshot.state as Array<
+      MakeRouteMatchUnion<TRouter>
+    >
+    return (opts?.select ? opts.select(matches) : matches) as UseMatchesResult<
+      TRouter,
+      TSelected
+    >
+  }
+
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  return useStore(router.stores.activeMatchesSnapshot, (matches) => {
+    const selected = opts?.select
+      ? opts.select(matches as Array<MakeRouteMatchUnion<TRouter>>)
+      : (matches as any)
+
+    if (opts?.structuralSharing ?? router.options.defaultStructuralSharing) {
+      const shared = replaceEqualDeep(previousResult.current, selected)
+      previousResult.current = shared
+      return shared
+    }
+
+    return selected
+  }) as UseMatchesResult<TRouter, TSelected>
 }
 
 /**

package/src/Scripts.tsx

@@ -1,5 +1,7 @@
+import { useStore } from '@tanstack/react-store'
+import { deepEqual } from '@tanstack/router-core'
+import { isServer } from '@tanstack/router-core/isServer'
 import { Asset } from './Asset'
-import { useRouterState } from './useRouterState'
 import { useRouter } from './useRouter'
 import type { RouterManagedTag } from '@tanstack/router-core'
 
@@ -10,54 +12,80 @@ import type { RouterManagedTag } from '@tanstack/router-core'
 export const Scripts = () => {
   const router = useRouter()
   const nonce = router.options.ssr?.nonce
-  const assetScripts = useRouterState({
-    select: (state) => {
-      const assetScripts: Array<RouterManagedTag> = []
-      const manifest = router.ssr?.manifest
 
-      if (!manifest) {
-        return []
-      }
+  const getAssetScripts = (matches: Array<any>) => {
+    const assetScripts: Array<RouterManagedTag> = []
+    const manifest = router.ssr?.manifest
 
-      state.matches
-        .map((match) => router.looseRoutesById[match.routeId]!)
-        .forEach((route) =>
-          manifest.routes[route.id]?.assets
-            ?.filter((d) => d.tag === 'script')
-            .forEach((asset) => {
-              assetScripts.push({
-                tag: 'script',
-                attrs: { ...asset.attrs, nonce },
-                children: asset.children,
-              } as any)
-            }),
-        )
+    if (!manifest) {
+      return []
+    }
 
-      return assetScripts
-    },
-    structuralSharing: true as any,
-  })
+    matches
+      .map((match) => router.looseRoutesById[match.routeId]!)
+      .forEach((route) =>
+        manifest.routes[route.id]?.assets
+          ?.filter((d) => d.tag === 'script')
+          .forEach((asset) => {
+            assetScripts.push({
+              tag: 'script',
+              attrs: { ...asset.attrs, nonce },
+              children: asset.children,
+            } as any)
+          }),
+      )
 
-  const { scripts } = useRouterState({
-    select: (state) => ({
-      scripts: (
-        state.matches
-          .map((match) => match.scripts!)
-          .flat(1)
-          .filter(Boolean) as Array<RouterManagedTag>
-      ).map(({ children, ...script }) => ({
-        tag: 'script',
-        attrs: {
-          ...script,
-          suppressHydrationWarning: true,
-          nonce,
-        },
-        children,
-      })),
-    }),
-    structuralSharing: true as any,
-  })
+    return assetScripts
+  }
+
+  const getScripts = (matches: Array<any>): Array<RouterManagedTag> =>
+    (
+      matches
+        .map((match) => match.scripts!)
+        .flat(1)
+        .filter(Boolean) as Array<RouterManagedTag>
+    ).map(
+      ({ children, ...script }) =>
+        ({
+          tag: 'script',
+          attrs: {
+            ...script,
+            suppressHydrationWarning: true,
+            nonce,
+          },
+          children,
+        }) satisfies RouterManagedTag,
+    )
+
+  if (isServer ?? router.isServer) {
+    const assetScripts = getAssetScripts(
+      router.stores.activeMatchesSnapshot.state,
+    )
+    const scripts = getScripts(router.stores.activeMatchesSnapshot.state)
+    return renderScripts(router, scripts, assetScripts)
+  }
+
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- condition is static
+  const assetScripts = useStore(
+    router.stores.activeMatchesSnapshot,
+    getAssetScripts,
+    deepEqual,
+  )
+  // eslint-disable-next-line react-hooks/rules-of-hooks -- condition is static
+  const scripts = useStore(
+    router.stores.activeMatchesSnapshot,
+    getScripts,
+    deepEqual,
+  )
+
+  return renderScripts(router, scripts, assetScripts)
+}
 
+function renderScripts(
+  router: ReturnType<typeof useRouter>,
+  scripts: Array<RouterManagedTag>,
+  assetScripts: Array<RouterManagedTag>,
+) {
   let serverBufferedScript: RouterManagedTag | undefined = undefined
 
   if (router.serverSsr) {