@tanstack/react-router 1.121.0-alpha.22 → 1.121.0-alpha.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-router",
-  "version": "1.121.0-alpha.22",
+  "version": "1.121.0-alpha.28",
   "description": "Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -38,7 +38,33 @@
         "default": "./dist/cjs/index.cjs"
       }
     },
-    "./package.json": "./package.json"
+    "./ssr/server": {
+      "import": {
+        "types": "./dist/esm/ssr/server.d.ts",
+        "default": "./dist/esm/ssr/server.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ssr/server.d.cts",
+        "default": "./dist/cjs/ssr/server.cjs"
+      }
+    },
+    "./ssr/client": {
+      "import": {
+        "types": "./dist/esm/ssr/client.d.ts",
+        "default": "./dist/esm/ssr/client.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ssr/client.d.cts",
+        "default": "./dist/cjs/ssr/client.cjs"
+      }
+    },
+    "./package.json": "./package.json",
+    "./llms": {
+      "import": {
+        "types": "./dist/llms/index.d.ts",
+        "default": "./dist/llms/index.js"
+      }
+    }
   },
   "sideEffects": false,
   "files": [
@@ -50,20 +76,20 @@
   },
   "dependencies": {
     "@tanstack/react-store": "^0.7.0",
-    "jsesc": "^3.1.0",
+    "isbot": "^5.1.22",
     "tiny-invariant": "^1.3.3",
     "tiny-warning": "^1.0.3",
-    "@tanstack/history": "1.121.0-alpha.1",
-    "@tanstack/router-core": "1.121.0-alpha.22"
+    "@tanstack/history": "1.121.0-alpha.28",
+    "@tanstack/router-core": "1.121.0-alpha.28"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.2.0",
-    "@types/jsesc": "^3.0.3",
     "@vitejs/plugin-react": "^4.3.4",
     "combinate": "^1.1.11",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "vibe-rules": "^0.2.57",
     "zod": "^3.24.2"
   },
   "peerDependencies": {

package/src/Asset.tsx

@@ -1,6 +1,17 @@
+import * as React from 'react'
 import type { RouterManagedTag } from '@tanstack/router-core'
 
-export function Asset({ tag, attrs, children }: RouterManagedTag): any {
+interface ScriptAttrs {
+  [key: string]: string | boolean | undefined
+  src?: string
+  suppressHydrationWarning?: boolean
+}
+
+export function Asset({
+  tag,
+  attrs,
+  children,
+}: RouterManagedTag): React.ReactElement | null {
   switch (tag) {
     case 'title':
       return (
@@ -16,25 +27,93 @@ export function Asset({ tag, attrs, children }: RouterManagedTag): any {
       return (
         <style
           {...attrs}
-          dangerouslySetInnerHTML={{ __html: children as any }}
+          dangerouslySetInnerHTML={{ __html: children as string }}
         />
       )
     case 'script':
-      if ((attrs as any) && (attrs as any).src) {
-        return <script {...attrs} suppressHydrationWarning />
-      }
-      if (typeof children === 'string')
-        return (
-          <script
-            {...attrs}
-            dangerouslySetInnerHTML={{
-              __html: children,
-            }}
-            suppressHydrationWarning
-          />
-        )
-      return null
+      return <Script attrs={attrs}>{children}</Script>
     default:
       return null
   }
 }
+
+function Script({
+  attrs,
+  children,
+}: {
+  attrs?: ScriptAttrs
+  children?: string
+}) {
+  React.useEffect(() => {
+    if (attrs?.src) {
+      const script = document.createElement('script')
+
+      for (const [key, value] of Object.entries(attrs)) {
+        if (
+          key !== 'suppressHydrationWarning' &&
+          value !== undefined &&
+          value !== false
+        ) {
+          script.setAttribute(
+            key,
+            typeof value === 'boolean' ? '' : String(value),
+          )
+        }
+      }
+
+      document.head.appendChild(script)
+
+      return () => {
+        if (script.parentNode) {
+          script.parentNode.removeChild(script)
+        }
+      }
+    }
+
+    if (typeof children === 'string') {
+      const script = document.createElement('script')
+      script.textContent = children
+
+      if (attrs) {
+        for (const [key, value] of Object.entries(attrs)) {
+          if (
+            key !== 'suppressHydrationWarning' &&
+            value !== undefined &&
+            value !== false
+          ) {
+            script.setAttribute(
+              key,
+              typeof value === 'boolean' ? '' : String(value),
+            )
+          }
+        }
+      }
+
+      document.head.appendChild(script)
+
+      return () => {
+        if (script.parentNode) {
+          script.parentNode.removeChild(script)
+        }
+      }
+    }
+
+    return undefined
+  }, [attrs, children])
+
+  if (attrs?.src && typeof attrs.src === 'string') {
+    return <script {...attrs} suppressHydrationWarning />
+  }
+
+  if (typeof children === 'string') {
+    return (
+      <script
+        {...attrs}
+        dangerouslySetInnerHTML={{ __html: children }}
+        suppressHydrationWarning
+      />
+    )
+  }
+
+  return null
+}

package/src/ClientOnly.tsx

@@ -2,7 +2,7 @@ import React from 'react'
 
 export interface ClientOnlyProps {
   /**
-   * The children to render if the JS is loaded.
+   * The children to render when the JS is loaded.
    */
   children: React.ReactNode
   /**

package/src/HeadContent.tsx

@@ -120,6 +120,21 @@ export const useTags = () => {
     structuralSharing: true as any,
   })
 
+  const styles = useRouterState({
+    select: (state) =>
+      (
+        state.matches
+          .map((match) => match.styles!)
+          .flat(1)
+          .filter(Boolean) as Array<RouterManagedTag>
+      ).map(({ children, ...attrs }) => ({
+        tag: 'style',
+        attrs,
+        children,
+      })),
+    structuralSharing: true as any,
+  })
+
   const headScripts = useRouterState({
     select: (state) =>
       (
@@ -142,6 +157,7 @@ export const useTags = () => {
       ...meta,
       ...preloadMeta,
       ...links,
+      ...styles,
       ...headScripts,
     ] as Array<RouterManagedTag>,
     (d) => {

package/src/Match.tsx

@@ -17,7 +17,12 @@ import { matchContext } from './matchContext'
 import { SafeFragment } from './SafeFragment'
 import { renderRouteNotFound } from './renderRouteNotFound'
 import { ScrollRestoration } from './scroll-restoration'
-import type { AnyRoute, ParsedLocation } from '@tanstack/router-core'
+import { ClientOnly } from './ClientOnly'
+import type {
+  AnyRoute,
+  ParsedLocation,
+  RootRouteOptions,
+} from '@tanstack/router-core'
 
 export const Match = React.memo(function MatchImpl({
   matchId,
@@ -25,16 +30,19 @@ export const Match = React.memo(function MatchImpl({
   matchId: string
 }) {
   const router = useRouter()
-  const routeId = useRouterState({
-    select: (s) => s.matches.find((d) => d.id === matchId)?.routeId as string,
+  const matchState = useRouterState({
+    select: (s) => {
+      const match = s.matches.find((d) => d.id === matchId)
+      invariant(
+        match,
+        `Could not find match for matchId "${matchId}". Please file an issue!`,
+      )
+      return pick(match, ['routeId', 'ssr', '_displayPending'])
+    },
+    structuralSharing: true as any,
   })
 
-  invariant(
-    routeId,
-    `Could not find routeId for matchId "${matchId}". Please file an issue!`,
-  )
-
-  const route: AnyRoute = router.routesById[routeId]
+  const route: AnyRoute = router.routesById[matchState.routeId]
 
   const PendingComponent =
     route.options.pendingComponent ?? router.options.defaultPendingComponent
@@ -52,12 +60,14 @@ export const Match = React.memo(function MatchImpl({
       router.options.notFoundRoute?.options.component)
     : route.options.notFoundComponent
 
+  const resolvedNoSsr =
+    matchState.ssr === false || matchState.ssr === 'data-only'
   const ResolvedSuspenseBoundary =
     // If we're on the root route, allow forcefully wrapping in suspense
-    (!route.isRoot || route.options.wrapInSuspense) &&
+    (!route.isRoot || route.options.wrapInSuspense || resolvedNoSsr) &&
     (route.options.wrapInSuspense ??
       PendingComponent ??
-      (route.options.errorComponent as any)?.preload)
+      ((route.options.errorComponent as any)?.preload || resolvedNoSsr))
       ? React.Suspense
       : SafeFragment
 
@@ -80,8 +90,11 @@ export const Match = React.memo(function MatchImpl({
     },
   })
 
+  const ShellComponent = route.isRoot
+    ? ((route.options as RootRouteOptions).shellComponent ?? SafeFragment)
+    : SafeFragment
   return (
-    <>
+    <ShellComponent>
       <matchContext.Provider value={matchId}>
         <ResolvedSuspenseBoundary fallback={pendingElement}>
           <ResolvedCatchBoundary
@@ -100,7 +113,7 @@ export const Match = React.memo(function MatchImpl({
                 // route ID which doesn't match the current route, rethrow the error
                 if (
                   !routeNotFoundComponent ||
-                  (error.routeId && error.routeId !== routeId) ||
+                  (error.routeId && error.routeId !== matchState.routeId) ||
                   (!error.routeId && !route.isRoot)
                 )
                   throw error
@@ -108,7 +121,13 @@ export const Match = React.memo(function MatchImpl({
                 return React.createElement(routeNotFoundComponent, error as any)
               }}
             >
-              <MatchInner matchId={matchId} />
+              {resolvedNoSsr || matchState._displayPending ? (
+                <ClientOnly fallback={pendingElement}>
+                  <MatchInner matchId={matchId} />
+                </ClientOnly>
+              ) : (
+                <MatchInner matchId={matchId} />
+              )}
             </ResolvedNotFoundBoundary>
           </ResolvedCatchBoundary>
         </ResolvedSuspenseBoundary>
@@ -119,14 +138,14 @@ export const Match = React.memo(function MatchImpl({
           <ScrollRestoration />
         </>
       ) : 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.
 // We render a script tag with a key that changes based on the current
-// location state.key. Also, because it's below the root layout, it
+// location state.__TSR_key. Also, because it's below the root layout, it
 // allows us to fire onRendered events even after a hydration mismatch
 // error that occurred above the root layout (like bad head/link tags,
 // which is common).
@@ -139,7 +158,7 @@ function OnRendered() {
 
   return (
     <script
-      key={router.latestLocation.state.key}
+      key={router.latestLocation.state.__TSR_key}
       suppressHydrationWarning
       ref={(el) => {
         if (
@@ -185,7 +204,13 @@ export const MatchInner = React.memo(function MatchInnerImpl({
       return {
         key,
         routeId,
-        match: pick(match, ['id', 'status', 'error']),
+        match: pick(match, [
+          'id',
+          'status',
+          'error',
+          '_forcePending',
+          '_displayPending',
+        ]),
       }
     },
     structuralSharing: true as any,
@@ -201,9 +226,45 @@ export const MatchInner = React.memo(function MatchInnerImpl({
     return <Outlet />
   }, [key, route.options.component, router.options.defaultComponent])
 
-  const RouteErrorComponent =
-    (route.options.errorComponent ?? router.options.defaultErrorComponent) ||
-    ErrorComponent
+  if (match._displayPending) {
+    throw router.getMatch(match.id)?.displayPendingPromise
+  }
+
+  if (match._forcePending) {
+    throw router.getMatch(match.id)?.minPendingPromise
+  }
+
+  // see also hydrate() in packages/router-core/src/ssr/ssr-client.ts
+  if (match.status === 'pending') {
+    // We're pending, and if we have a minPendingMs, we need to wait for it
+    const pendingMinMs =
+      route.options.pendingMinMs ?? router.options.defaultPendingMinMs
+
+    if (pendingMinMs && !router.getMatch(match.id)?.minPendingPromise) {
+      // Create a promise that will resolve after the minPendingMs
+      if (!router.isServer) {
+        const minPendingPromise = createControlledPromise<void>()
+
+        Promise.resolve().then(() => {
+          router.updateMatch(match.id, (prev) => ({
+            ...prev,
+            minPendingPromise,
+          }))
+        })
+
+        setTimeout(() => {
+          minPendingPromise.resolve()
+
+          // We've handled the minPendingPromise, so we can delete it
+          router.updateMatch(match.id, (prev) => ({
+            ...prev,
+            minPendingPromise: undefined,
+          }))
+        }, pendingMinMs)
+      }
+    }
+    throw router.getMatch(match.id)?.loadPromise
+  }
 
   if (match.status === 'notFound') {
     invariant(isNotFound(match.error), 'Expected a notFound error')
@@ -229,6 +290,10 @@ export const MatchInner = React.memo(function MatchInnerImpl({
     // renderToPipeableStream to not hang indefinitely.
     // We'll serialize the error and rethrow it on the client.
     if (router.isServer) {
+      const RouteErrorComponent =
+        (route.options.errorComponent ??
+          router.options.defaultErrorComponent) ||
+        ErrorComponent
       return (
         <RouteErrorComponent
           error={match.error as any}
@@ -243,37 +308,6 @@ export const MatchInner = React.memo(function MatchInnerImpl({
     throw match.error
   }
 
-  if (match.status === 'pending') {
-    // We're pending, and if we have a minPendingMs, we need to wait for it
-    const pendingMinMs =
-      route.options.pendingMinMs ?? router.options.defaultPendingMinMs
-
-    if (pendingMinMs && !router.getMatch(match.id)?.minPendingPromise) {
-      // Create a promise that will resolve after the minPendingMs
-      if (!router.isServer) {
-        const minPendingPromise = createControlledPromise<void>()
-
-        Promise.resolve().then(() => {
-          router.updateMatch(match.id, (prev) => ({
-            ...prev,
-            minPendingPromise,
-          }))
-        })
-
-        setTimeout(() => {
-          minPendingPromise.resolve()
-
-          // We've handled the minPendingPromise, so we can delete it
-          router.updateMatch(match.id, (prev) => ({
-            ...prev,
-            minPendingPromise: undefined,
-          }))
-        }, pendingMinMs)
-      }
-    }
-    throw router.getMatch(match.id)?.loadPromise
-  }
-
   return out
 })
 
@@ -310,13 +344,6 @@ export const Outlet = React.memo(function OutletImpl() {
     <router.options.defaultPendingComponent />
   ) : null
 
-  if (router.isShell)
-    return (
-      <React.Suspense fallback={pendingElement}>
-        <ShellInner />
-      </React.Suspense>
-    )
-
   if (parentGlobalNotFound) {
     return renderRouteNotFound(router, route, undefined)
   }
@@ -335,7 +362,3 @@ export const Outlet = React.memo(function OutletImpl() {
 
   return nextMatch
 })
-
-function ShellInner(): React.ReactElement {
-  throw new Error('ShellBoundaryError')
-}

package/src/Matches.tsx

@@ -11,7 +11,6 @@ import type {
   StructuralSharingOption,
   ValidateSelected,
 } from './structuralSharing'
-import type { ReactNode } from './route'
 import type {
   AnyRouter,
   DeepPartial,
@@ -35,6 +34,7 @@ declare module '@tanstack/router-core' {
     meta?: Array<React.JSX.IntrinsicElements['meta'] | undefined>
     links?: Array<React.JSX.IntrinsicElements['link'] | undefined>
     scripts?: Array<React.JSX.IntrinsicElements['script'] | undefined>
+    styles?: Array<React.JSX.IntrinsicElements['style'] | undefined>
     headScripts?: Array<React.JSX.IntrinsicElements['script'] | undefined>
   }
 }
@@ -48,13 +48,13 @@ export function Matches() {
 
   // Do not render a root Suspense during SSR or hydrating from SSR
   const ResolvedSuspense =
-    router.isServer || (typeof document !== 'undefined' && router.clientSsr)
+    router.isServer || (typeof document !== 'undefined' && router.ssr)
       ? SafeFragment
       : React.Suspense
 
   const inner = (
     <ResolvedSuspense fallback={pendingElement}>
-      <Transitioner />
+      {!router.isServer && <Transitioner />}
       <MatchesInner />
     </ResolvedSuspense>
   )
@@ -67,6 +67,7 @@ export function Matches() {
 }
 
 function MatchesInner() {
+  const router = useRouter()
   const matchId = useRouterState({
     select: (s) => {
       return s.matches[0]?.id
@@ -77,21 +78,27 @@ function MatchesInner() {
     select: (s) => s.loadedAt,
   })
 
+  const matchComponent = matchId ? <Match matchId={matchId} /> : null
+
   return (
     <matchContext.Provider value={matchId}>
-      <CatchBoundary
-        getResetKey={() => resetKey}
-        errorComponent={ErrorComponent}
-        onCatch={(error) => {
-          warning(
-            false,
-            `The following error wasn't caught by any route! At the very least, consider setting an 'errorComponent' in your RootRoute!`,
-          )
-          warning(false, error.message || error.toString())
-        }}
-      >
-        {matchId ? <Match matchId={matchId} /> : null}
-      </CatchBoundary>
+      {router.options.disableGlobalCatchBoundary ? (
+        matchComponent
+      ) : (
+        <CatchBoundary
+          getResetKey={() => resetKey}
+          errorComponent={ErrorComponent}
+          onCatch={(error) => {
+            warning(
+              false,
+              `The following error wasn't caught by any route! At the very least, consider setting an 'errorComponent' in your RootRoute!`,
+            )
+            warning(false, error.message || error.toString())
+          }}
+        >
+          {matchComponent}
+        </CatchBoundary>
+      )}
     </matchContext.Provider>
   )
 }
@@ -154,7 +161,7 @@ export type MakeMatchRouteOptions<
           TRouter['routeTree'],
           ResolveRelativePath<TFrom, NoInfer<TTo>>
         >['types']['allParams'],
-      ) => ReactNode)
+      ) => React.ReactNode)
     | React.ReactNode
 }
 

package/src/ScriptOnce.tsx

@@ -1,8 +1,5 @@
-import jsesc from 'jsesc'
-
 export function ScriptOnce({
   children,
-  log,
 }: {
   children: string
   log?: boolean
@@ -14,18 +11,9 @@ export function ScriptOnce({
 
   return (
     <script
-      className="tsr-once"
+      className="$tsr"
       dangerouslySetInnerHTML={{
-        __html: [
-          children,
-          (log ?? true) && process.env.NODE_ENV === 'development'
-            ? `console.info(\`Injected From Server:
-${jsesc(children.toString(), { quotes: 'backtick' })}\`)`
-            : '',
-          'if (typeof __TSR_SSR__ !== "undefined") __TSR_SSR__.cleanScripts()',
-        ]
-          .filter(Boolean)
-          .join('\n'),
+        __html: [children].filter(Boolean).join('\n'),
       }}
     />
   )

package/src/Transitioner.tsx

@@ -11,14 +11,14 @@ import { useRouterState } from './useRouterState'
 export function Transitioner() {
   const router = useRouter()
   const mountLoadForRouter = React.useRef({ router, mounted: false })
-  const isLoading = useRouterState({
-    select: ({ isLoading }) => isLoading,
-  })
 
   const [isTransitioning, setIsTransitioning] = React.useState(false)
   // Track pending state changes
-  const hasPendingMatches = useRouterState({
-    select: (s) => s.matches.some((d) => d.status === 'pending'),
+  const { hasPendingMatches, isLoading } = useRouterState({
+    select: (s) => ({
+      isLoading: s.isLoading,
+      hasPendingMatches: s.matches.some((d) => d.status === 'pending'),
+    }),
     structuralSharing: true,
   })
 
@@ -30,14 +30,12 @@ export function Transitioner() {
   const isPagePending = isLoading || hasPendingMatches
   const previousIsPagePending = usePrevious(isPagePending)
 
-  if (!router.isServer) {
-    router.startTransition = (fn: () => void) => {
-      setIsTransitioning(true)
-      React.startTransition(() => {
-        fn()
-        setIsTransitioning(false)
-      })
-    }
+  router.startTransition = (fn: () => void) => {
+    setIsTransitioning(true)
+    React.startTransition(() => {
+      fn()
+      setIsTransitioning(false)
+    })
   }
 
   // Subscribe to location changes
@@ -69,7 +67,8 @@ export function Transitioner() {
   // Try to load the initial location
   useLayoutEffect(() => {
     if (
-      (typeof window !== 'undefined' && router.clientSsr) ||
+      // if we are hydrating from SSR, loading is triggered in ssr-client
+      (typeof window !== 'undefined' && router.ssr) ||
       (mountLoadForRouter.current.router === router &&
         mountLoadForRouter.current.mounted)
     ) {