@tanstack/vue-router 1.141.4 → 1.141.6

package/src/Match.tsx

@@ -9,6 +9,7 @@ import {
   rootRouteId,
 } from '@tanstack/router-core'
 import { CatchBoundary, ErrorComponent } from './CatchBoundary'
+import { ClientOnly } from './ClientOnly'
 import { useRouterState } from './useRouterState'
 import { useRouter } from './useRouter'
 import { CatchNotFound } from './not-found'
@@ -16,7 +17,7 @@ import { matchContext } from './matchContext'
 import { renderRouteNotFound } from './renderRouteNotFound'
 import { ScrollRestoration } from './scroll-restoration'
 import type { VNode } from 'vue'
-import type { AnyRoute } from '@tanstack/router-core'
+import type { AnyRoute, RootRouteOptions } from '@tanstack/router-core'
 
 export const Match = Vue.defineComponent({
   name: 'Match',
@@ -67,6 +68,8 @@ export const Match = Vue.defineComponent({
           routeId,
           parentRouteId,
           loadedAt: s.loadedAt,
+          ssr: match.ssr,
+          _displayPending: match._displayPending,
         }
       },
     })
@@ -86,6 +89,10 @@ export const Match = Vue.defineComponent({
         router?.options?.defaultPendingComponent,
     )
 
+    const pendingElement = Vue.computed(() =>
+      PendingComponent.value ? Vue.h(PendingComponent.value) : undefined,
+    )
+
     const routeErrorComponent = Vue.computed(
       () =>
         route.value?.options?.errorComponent ??
@@ -104,6 +111,17 @@ export const Match = Vue.defineComponent({
         : route.value?.options?.notFoundComponent,
     )
 
+    const hasShellComponent = Vue.computed(() => {
+      if (!route.value?.isRoot) return false
+      return !!(route.value.options as RootRouteOptions).shellComponent
+    })
+
+    const ShellComponent = Vue.computed(() =>
+      hasShellComponent.value
+        ? ((route.value!.options as RootRouteOptions).shellComponent as any)
+        : null,
+    )
+
     // Create a ref for the current matchId that we provide to child components
     // This ref is updated to the ACTUAL matchId found (which may differ from props during transitions)
     const matchIdRef = Vue.ref(matchData.value?.matchId ?? props.matchId)
@@ -127,82 +145,89 @@ export const Match = Vue.defineComponent({
       // Use the actual matchId from matchData, not props (which may be stale)
       const actualMatchId = matchData.value?.matchId ?? props.matchId
 
-      // Determine which components to render
-      let content: VNode = Vue.h(MatchInner, { matchId: actualMatchId })
-
-      // Wrap in NotFound boundary if needed
-      if (routeNotFoundComponent.value) {
-        content = Vue.h(CatchNotFound, {
-          fallback: (error: any) => {
-            // If the current not found handler doesn't exist or it has a
-            // route ID which doesn't match the current route, rethrow the error
-            if (
-              !routeNotFoundComponent.value ||
-              (error.routeId && error.routeId !== matchData.value?.routeId) ||
-              (!error.routeId && route.value && !route.value.isRoot)
+      const resolvedNoSsr =
+        matchData.value?.ssr === false || matchData.value?.ssr === 'data-only'
+      const shouldClientOnly =
+        resolvedNoSsr || !!matchData.value?._displayPending
+
+      const renderMatchContent = (): VNode => {
+        const matchInner = Vue.h(MatchInner, { matchId: actualMatchId })
+
+        let content: VNode = shouldClientOnly
+          ? Vue.h(
+              ClientOnly,
+              {
+                fallback: pendingElement.value,
+              },
+              {
+                default: () => matchInner,
+              },
             )
-              throw error
-
-            return Vue.h(routeNotFoundComponent.value, error)
-          },
-          children: content,
-        })
-      }
+          : matchInner
+
+        // Wrap in NotFound boundary if needed
+        if (routeNotFoundComponent.value) {
+          content = Vue.h(CatchNotFound, {
+            fallback: (error: any) => {
+              // If the current not found handler doesn't exist or it has a
+              // route ID which doesn't match the current route, rethrow the error
+              if (
+                !routeNotFoundComponent.value ||
+                (error.routeId && error.routeId !== matchData.value?.routeId) ||
+                (!error.routeId && route.value && !route.value.isRoot)
+              )
+                throw error
+
+              return Vue.h(routeNotFoundComponent.value, error)
+            },
+            children: content,
+          })
+        }
 
-      // Wrap in error boundary if needed
-      if (routeErrorComponent.value) {
-        content = CatchBoundary({
-          getResetKey: () => matchData.value?.loadedAt ?? 0,
-          errorComponent: routeErrorComponent.value || ErrorComponent,
-          onCatch: (error: Error) => {
-            // Forward not found errors (we don't want to show the error component for these)
-            if (isNotFound(error)) throw error
-            warning(false, `Error in route match: ${actualMatchId}`)
-            routeOnCatch.value?.(error)
-          },
-          children: content,
-        })
-      }
+        // Wrap in error boundary if needed
+        if (routeErrorComponent.value) {
+          content = CatchBoundary({
+            getResetKey: () => matchData.value?.loadedAt ?? 0,
+            errorComponent: routeErrorComponent.value || ErrorComponent,
+            onCatch: (error: Error) => {
+              // Forward not found errors (we don't want to show the error component for these)
+              if (isNotFound(error)) throw error
+              warning(false, `Error in route match: ${actualMatchId}`)
+              routeOnCatch.value?.(error)
+            },
+            children: content,
+          })
+        }
 
-      // Wrap in suspense if needed
-      // Root routes should also wrap in Suspense if they have a pendingComponent
-      const needsSuspense =
-        route.value &&
-        (route.value?.options?.wrapInSuspense ??
-          PendingComponent.value ??
-          false)
+        // Add scroll restoration if needed
+        const withScrollRestoration: Array<VNode> = [
+          content,
+          matchData.value?.parentRouteId === rootRouteId &&
+          router.options.scrollRestoration
+            ? Vue.h(Vue.Fragment, null, [
+                Vue.h(OnRendered),
+                Vue.h(ScrollRestoration),
+              ])
+            : null,
+        ].filter(Boolean) as Array<VNode>
+
+        // Return single child directly to avoid Fragment wrapper that causes hydration mismatch
+        if (withScrollRestoration.length === 1) {
+          return withScrollRestoration[0]!
+        }
 
-      if (needsSuspense) {
-        content = Vue.h(
-          Vue.Suspense,
-          {
-            fallback: PendingComponent.value
-              ? Vue.h(PendingComponent.value)
-              : null,
-          },
-          {
-            default: () => content,
-          },
-        )
+        return Vue.h(Vue.Fragment, null, withScrollRestoration)
       }
 
-      // Add scroll restoration if needed
-      const withScrollRestoration: Array<VNode> = [
-        content,
-        matchData.value?.parentRouteId === rootRouteId &&
-        router.options.scrollRestoration
-          ? Vue.h(Vue.Fragment, null, [
-              Vue.h(OnRendered),
-              Vue.h(ScrollRestoration),
-            ])
-          : null,
-      ].filter(Boolean) as Array<VNode>
-
-      // Return single child directly to avoid Fragment wrapper that causes hydration mismatch
-      if (withScrollRestoration.length === 1) {
-        return withScrollRestoration[0]!
+      if (!hasShellComponent.value) {
+        return renderMatchContent()
       }
-      return Vue.h(Vue.Fragment, null, withScrollRestoration)
+
+      return Vue.h(ShellComponent.value, null, {
+        // Important: return a fresh VNode on each slot invocation so that shell
+        // components can re-render without reusing a cached VNode instance.
+        default: () => renderMatchContent(),
+      })
     }
   },
 })
@@ -304,6 +329,9 @@ export const MatchInner = Vue.defineComponent({
             id: match.id,
             status: match.status,
             error: match.error,
+            ssr: match.ssr,
+            _forcePending: match._forcePending,
+            _displayPending: match._displayPending,
           },
           remountKey,
         }
@@ -320,11 +348,25 @@ export const MatchInner = Vue.defineComponent({
 
     return (): VNode | null => {
       // If match doesn't exist, return null (component is being unmounted or not ready)
-      if (!combinedState.value || !match.value || !route.value) {
-        return null
-      }
+      if (!combinedState.value || !match.value || !route.value) return null
 
       // Handle different match statuses
+      if (match.value._displayPending) {
+        const PendingComponent =
+          route.value.options.pendingComponent ??
+          router.options.defaultPendingComponent
+
+        return PendingComponent ? Vue.h(PendingComponent) : null
+      }
+
+      if (match.value._forcePending) {
+        const PendingComponent =
+          route.value.options.pendingComponent ??
+          router.options.defaultPendingComponent
+
+        return PendingComponent ? Vue.h(PendingComponent) : null
+      }
+
       if (match.value.status === 'notFound') {
         invariant(isNotFound(match.value.error), 'Expected a notFound error')
         return renderRouteNotFound(router, route.value, match.value.error)

package/src/Transitioner.tsx

@@ -136,6 +136,13 @@ export function useTransitionerSetup() {
 
   Vue.onMounted(() => {
     isMounted.value = true
+    if (!isAnyPending.value) {
+      router.__store.setState((s) =>
+        s.status === 'pending'
+          ? { ...s, status: 'idle', resolvedLocation: s.location }
+          : s,
+      )
+    }
   })
 
   Vue.onUnmounted(() => {
@@ -201,6 +208,14 @@ export function useTransitionerSetup() {
   Vue.watch(isAnyPending, (newValue) => {
     if (!isMounted.value) return
     try {
+      if (!newValue && router.__store.state.status === 'pending') {
+        router.__store.setState((s) => ({
+          ...s,
+          status: 'idle',
+          resolvedLocation: s.location,
+        }))
+      }
+
       // The router was pending and now it's not
       if (previousIsAnyPending.value.previous && !newValue) {
         const changeInfo = getLocationChangeInfo(router.state)
@@ -209,12 +224,6 @@ export function useTransitionerSetup() {
           ...changeInfo,
         })
 
-        router.__store.setState((s) => ({
-          ...s,
-          status: 'idle',
-          resolvedLocation: s.location,
-        }))
-
         if (changeInfo.hrefChanged) {
           handleHashScroll(router)
         }

package/src/index.tsx

@@ -219,6 +219,7 @@ export type {
   ActiveLinkOptions,
   LinkProps,
   LinkComponent,
+  LinkComponentRoute,
   LinkComponentProps,
   CreateLinkProps,
 } from './link'
@@ -346,3 +347,4 @@ export type {
   LocationRewrite,
   LocationRewriteFunction,
 } from '@tanstack/router-core'
+export { ClientOnly } from './ClientOnly'

package/src/lazyRouteComponent.tsx

@@ -1,5 +1,6 @@
 import * as Vue from 'vue'
 import { Outlet } from './Match'
+import { ClientOnly } from './ClientOnly'
 import type { AsyncRouteComponent } from './route'
 
 // If the load fails due to module not found, it may mean a new version of
@@ -19,34 +20,6 @@ function isModuleNotFoundError(error: any): boolean {
   )
 }
 
-export function ClientOnly(props: { children?: any; fallback?: Vue.VNode }) {
-  const hydrated = useHydrated()
-
-  return () => {
-    if (hydrated.value) {
-      return props.children
-    }
-    return props.fallback || null
-  }
-}
-
-export function useHydrated() {
-  // Only hydrate on client-side, never on server
-  const hydrated = Vue.ref(false)
-
-  // If on server, return false
-  if (typeof window === 'undefined') {
-    return Vue.computed(() => false)
-  }
-
-  // On client, set to true once mounted
-  Vue.onMounted(() => {
-    hydrated.value = true
-  })
-
-  return hydrated
-}
-
 export function lazyRouteComponent<
   T extends Record<string, any>,
   TKey extends keyof T = 'default',
@@ -156,10 +129,15 @@ export function lazyRouteComponent<
 
         // If SSR is disabled for this component
         if (ssr?.() === false) {
-          return Vue.h(ClientOnly, {
-            fallback: Vue.h(Outlet),
-            children: Vue.h(component.value, props),
-          })
+          return Vue.h(
+            ClientOnly,
+            {
+              fallback: Vue.h(Outlet),
+            },
+            {
+              default: () => Vue.h(component.value, props),
+            },
+          )
         }
 
         // Regular render with the loaded component

package/src/link.tsx

@@ -630,6 +630,26 @@ export type LinkComponent<TComp> = <
   props: LinkComponentProps<TComp, TRouter, TFrom, TTo, TMaskFrom, TMaskTo>,
 ) => Vue.VNode
 
+export interface LinkComponentRoute<
+  in out TDefaultFrom extends string = string,
+> {
+  defaultFrom: TDefaultFrom
+  <
+    TRouter extends AnyRouter = RegisteredRouter,
+    const TTo extends string | undefined = undefined,
+    const TMaskTo extends string = '',
+  >(
+    props: LinkComponentProps<
+      'a',
+      TRouter,
+      this['defaultFrom'],
+      TTo,
+      this['defaultFrom'],
+      TMaskTo
+    >,
+  ): Vue.VNode
+}
+
 export function createLink<const TComp>(
   Comp: Constrain<TComp, any, (props: CreateLinkProps) => Vue.VNode>,
 ): LinkComponent<TComp> {

package/src/route.ts

@@ -4,6 +4,8 @@ import {
   BaseRouteApi,
   notFound,
 } from '@tanstack/router-core'
+import * as Vue from 'vue'
+import { Link } from './link'
 import { useLoaderData } from './useLoaderData'
 import { useLoaderDeps } from './useLoaderDeps'
 import { useParams } from './useParams'
@@ -42,8 +44,8 @@ import type { UseMatchRoute } from './useMatch'
 import type { UseLoaderDepsRoute } from './useLoaderDeps'
 import type { UseParamsRoute } from './useParams'
 import type { UseSearchRoute } from './useSearch'
-import type * as Vue from 'vue'
 import type { UseRouteContextRoute } from './useRouteContext'
+import type { LinkComponentRoute } from './link'
 
 // Structural type for Vue SFC components (.vue files)
 // Uses structural matching to accept Vue components without breaking
@@ -73,6 +75,7 @@ declare module '@tanstack/router-core' {
     useLoaderDeps: UseLoaderDepsRoute<TId>
     useLoaderData: UseLoaderDataRoute<TId>
     useNavigate: () => UseNavigateResult<TFullPath>
+    Link: LinkComponentRoute<TFullPath>
   }
 }
 
@@ -140,6 +143,19 @@ export class RouteApi<
   notFound = (opts?: NotFoundError) => {
     return notFound({ routeId: this.id as string, ...opts })
   }
+
+  Link: LinkComponentRoute<RouteTypesById<TRouter, TId>['fullPath']> = ((
+    props,
+    ctx?: Vue.SetupContext,
+  ) => {
+    const router = useRouter()
+    const fullPath = router.routesById[this.id as string].fullPath
+    return Vue.h(
+      Link as any,
+      { from: fullPath as never, ...(props as any) },
+      ctx?.slots,
+    )
+  }) as LinkComponentRoute<RouteTypesById<TRouter, TId>['fullPath']>
 }
 
 export class Route<
@@ -277,6 +293,14 @@ export class Route<
   useNavigate = (): UseNavigateResult<TFullPath> => {
     return useNavigate({ from: this.fullPath })
   }
+
+  Link: LinkComponentRoute<TFullPath> = ((props, ctx?: Vue.SetupContext) => {
+    return Vue.h(
+      Link as any,
+      { from: this.fullPath as never, ...(props as any) },
+      ctx?.slots,
+    )
+  }) as LinkComponentRoute<TFullPath>
 }
 
 export function createRoute<
@@ -515,6 +539,14 @@ export class RootRoute<
   useNavigate = (): UseNavigateResult<'/'> => {
     return useNavigate({ from: this.fullPath })
   }
+
+  Link: LinkComponentRoute<'/'> = ((props, ctx?: Vue.SetupContext) => {
+    return Vue.h(
+      Link as any,
+      { from: this.fullPath as never, ...(props as any) },
+      ctx?.slots,
+    )
+  }) as LinkComponentRoute<'/'>
 }
 
 export function createRouteMask<