@tanstack/router-core 1.124.2 → 1.125.1

package/src/router.ts

@@ -57,6 +57,7 @@ import type {
   RouteContextOptions,
   RouteMask,
   SearchMiddleware,
+  SsrContextOptions,
 } from './route'
 import type {
   FullSearchSchema,
@@ -342,7 +343,12 @@ export interface RouterOptions<
    */
   isServer?: boolean
 
-  defaultSsr?: boolean
+  /**
+   * The default `ssr` a route should use if no `ssr` is provided.
+   *
+   * @default true
+   */
+  defaultSsr?: boolean | 'data-only'
 
   search?: {
     /**
@@ -946,7 +952,6 @@ export class RouterCore<
       initRoute: (route, i) => {
         route.init({
           originalIndex: i,
-          defaultSsr: this.options.defaultSsr,
         })
       },
     })
@@ -960,7 +965,6 @@ export class RouterCore<
     if (notFoundRoute) {
       notFoundRoute.init({
         originalIndex: 99999999999,
-        defaultSsr: this.options.defaultSsr,
       })
       this.routesById[notFoundRoute.id] = notFoundRoute
     }
@@ -1387,7 +1391,13 @@ export class RouterCore<
     if (!match) return
 
     match.abortController.abort()
-    clearTimeout(match.pendingTimeout)
+    this.updateMatch(id, (prev) => {
+      clearTimeout(prev.pendingTimeout)
+      return {
+        ...prev,
+        pendingTimeout: undefined,
+      }
+    })
   }
 
   cancelMatches = () => {
@@ -1787,7 +1797,11 @@ export class RouterCore<
       }
     }
     // Match the routes
-    const pendingMatches = this.matchRoutes(this.latestLocation)
+    let pendingMatches = this.matchRoutes(this.latestLocation)
+    // in SPA mode we only want to load the root route
+    if (this.isShell) {
+      pendingMatches = pendingMatches.slice(0, 1)
+    }
 
     // Ingest the new matches
     this.__store.setState((s) => ({
@@ -1806,7 +1820,6 @@ export class RouterCore<
   load: LoadFn = async (opts?: { sync?: boolean }): Promise<void> => {
     let redirect: AnyRedirect | undefined
     let notFound: NotFoundError | undefined
-
     let loadPromise: Promise<void>
 
     // eslint-disable-next-line prefer-const
@@ -2061,6 +2074,40 @@ export class RouterCore<
     const triggerOnReady = async () => {
       if (!rendered) {
         rendered = true
+
+        // create a minPendingPromise for matches that have forcePending set to true
+        // usually the minPendingPromise is created in the Match component if a pending match is rendered
+        // however, this might be too late if the match synchronously resolves
+        if (!allPreload && !this.isServer) {
+          matches.forEach((match) => {
+            const {
+              id: matchId,
+              routeId,
+              _forcePending,
+              minPendingPromise,
+            } = match
+            const route = this.looseRoutesById[routeId]!
+            const pendingMinMs =
+              route.options.pendingMinMs ?? this.options.defaultPendingMinMs
+            if (_forcePending && pendingMinMs && !minPendingPromise) {
+              const minPendingPromise = createControlledPromise<void>()
+              updateMatch(matchId, (prev) => ({
+                ...prev,
+                minPendingPromise,
+              }))
+
+              setTimeout(() => {
+                minPendingPromise.resolve()
+                // We've handled the minPendingPromise, so we can delete it
+                updateMatch(matchId, (prev) => ({
+                  ...prev,
+                  minPendingPromise: undefined,
+                }))
+              }, pendingMinMs)
+            }
+          })
+        }
+
         await onReady?.()
       }
     }
@@ -2069,6 +2116,12 @@ export class RouterCore<
       return !!(allPreload && !this.state.matches.find((d) => d.id === matchId))
     }
 
+    // make sure the pending component is immediately rendered when hydrating a match that is not SSRed
+    // the pending component was already rendered on the server and we want to keep it shown on the client until minPendingMs is reached
+    if (!this.isServer && this.state.matches.find((d) => d._forcePending)) {
+      triggerOnReady()
+    }
+
     const handleRedirectAndNotFound = (match: AnyRouteMatch, err: any) => {
       if (isRedirect(err) || isNotFound(err)) {
         if (isRedirect(err)) {
@@ -2120,6 +2173,21 @@ export class RouterCore<
       }
     }
 
+    const shouldSkipLoader = (matchId: string) => {
+      const match = this.getMatch(matchId)!
+      // upon hydration, we skip the loader if the match has been dehydrated on the server
+      if (!this.isServer && match._dehydrated) {
+        return true
+      }
+
+      if (this.isServer) {
+        if (match.ssr === false) {
+          return true
+        }
+      }
+      return false
+    }
+
     try {
       await new Promise<void>((resolveAll, rejectAll) => {
         ;(async () => {
@@ -2169,12 +2237,73 @@ export class RouterCore<
             for (const [index, { id: matchId, routeId }] of matches.entries()) {
               const existingMatch = this.getMatch(matchId)!
               const parentMatchId = matches[index - 1]?.id
+              const parentMatch = parentMatchId
+                ? this.getMatch(parentMatchId)!
+                : undefined
 
               const route = this.looseRoutesById[routeId]!
 
               const pendingMs =
                 route.options.pendingMs ?? this.options.defaultPendingMs
 
+              // on the server, determine whether SSR the current match or not
+              if (this.isServer) {
+                const defaultSsr = this.options.defaultSsr ?? true
+                let ssr: boolean | 'data-only'
+                if (parentMatch?.ssr === false) {
+                  ssr = false
+                } else {
+                  let tempSsr: boolean | 'data-only'
+                  if (route.options.ssr === undefined) {
+                    tempSsr = defaultSsr
+                  } else if (typeof route.options.ssr === 'function') {
+                    const { search, params } = this.getMatch(matchId)!
+
+                    function makeMaybe(value: any, error: any) {
+                      if (error) {
+                        return { status: 'error' as const, error }
+                      }
+                      return { status: 'success' as const, value }
+                    }
+
+                    const ssrFnContext: SsrContextOptions<any, any, any> = {
+                      search: makeMaybe(search, existingMatch.searchError),
+                      params: makeMaybe(params, existingMatch.paramsError),
+                      location,
+                      matches: matches.map((match) => ({
+                        index: match.index,
+                        pathname: match.pathname,
+                        fullPath: match.fullPath,
+                        staticData: match.staticData,
+                        id: match.id,
+                        routeId: match.routeId,
+                        search: makeMaybe(match.search, match.searchError),
+                        params: makeMaybe(match.params, match.paramsError),
+                        ssr: match.ssr,
+                      })),
+                    }
+                    tempSsr =
+                      (await route.options.ssr(ssrFnContext)) ?? defaultSsr
+                  } else {
+                    tempSsr = route.options.ssr
+                  }
+
+                  if (tempSsr === true && parentMatch?.ssr === 'data-only') {
+                    ssr = 'data-only'
+                  } else {
+                    ssr = tempSsr
+                  }
+                }
+                updateMatch(matchId, (prev) => ({
+                  ...prev,
+                  ssr,
+                }))
+              }
+
+              if (shouldSkipLoader(matchId)) {
+                continue
+              }
+
               const shouldPending = !!(
                 onReady &&
                 !this.isServer &&
@@ -2189,21 +2318,31 @@ export class RouterCore<
               )
 
               let executeBeforeLoad = true
-              if (
-                // If we are in the middle of a load, either of these will be present
-                // (not to be confused with `loadPromise`, which is always defined)
-                existingMatch.beforeLoadPromise ||
-                existingMatch.loaderPromise
-              ) {
-                if (shouldPending) {
-                  setTimeout(() => {
+              const setupPendingTimeout = () => {
+                if (
+                  shouldPending &&
+                  this.getMatch(matchId)!.pendingTimeout === undefined
+                ) {
+                  const pendingTimeout = setTimeout(() => {
                     try {
                       // Update the match and prematurely resolve the loadMatches promise so that
                       // the pending component can start rendering
                       triggerOnReady()
                     } catch {}
                   }, pendingMs)
+                  updateMatch(matchId, (prev) => ({
+                    ...prev,
+                    pendingTimeout,
+                  }))
                 }
+              }
+              if (
+                // If we are in the middle of a load, either of these will be present
+                // (not to be confused with `loadPromise`, which is always defined)
+                existingMatch.beforeLoadPromise ||
+                existingMatch.loaderPromise
+              ) {
+                setupPendingTimeout()
 
                 // Wait for the beforeLoad to resolve before we continue
                 await existingMatch.beforeLoadPromise
@@ -2231,21 +2370,6 @@ export class RouterCore<
                       beforeLoadPromise: createControlledPromise<void>(),
                     }
                   })
-                  const abortController = new AbortController()
-
-                  let pendingTimeout: ReturnType<typeof setTimeout>
-
-                  if (shouldPending) {
-                    // If we might show a pending component, we need to wait for the
-                    // pending promise to resolve before we start showing that state
-                    pendingTimeout = setTimeout(() => {
-                      try {
-                        // Update the match and prematurely resolve the loadMatches promise so that
-                        // the pending component can start rendering
-                        triggerOnReady()
-                      } catch {}
-                    }, pendingMs)
-                  }
 
                   const { paramsError, searchError } = this.getMatch(matchId)!
 
@@ -2257,19 +2381,20 @@ export class RouterCore<
                     handleSerialError(index, searchError, 'VALIDATE_SEARCH')
                   }
 
-                  const getParentMatchContext = () =>
-                    parentMatchId
-                      ? this.getMatch(parentMatchId)!.context
-                      : (this.options.context ?? {})
+                  setupPendingTimeout()
+
+                  const abortController = new AbortController()
+
+                  const parentMatchContext =
+                    parentMatch?.context ?? this.options.context ?? {}
 
                   updateMatch(matchId, (prev) => ({
                     ...prev,
                     isFetching: 'beforeLoad',
                     fetchCount: prev.fetchCount + 1,
                     abortController,
-                    pendingTimeout,
                     context: {
-                      ...getParentMatchContext(),
+                      ...parentMatchContext,
                       ...prev.__routeContext,
                     },
                   }))
@@ -2315,7 +2440,7 @@ export class RouterCore<
                       ...prev,
                       __beforeLoadContext: beforeLoadContext,
                       context: {
-                        ...getParentMatchContext(),
+                        ...parentMatchContext,
                         ...prev.__routeContext,
                         ...beforeLoadContext,
                       },
@@ -2346,10 +2471,65 @@ export class RouterCore<
                 (async () => {
                   let loaderShouldRunAsync = false
                   let loaderIsRunningAsync = false
+                  const route = this.looseRoutesById[routeId]!
+
+                  const executeHead = async () => {
+                    const match = this.getMatch(matchId)
+                    // in case of a redirecting match during preload, the match does not exist
+                    if (!match) {
+                      return
+                    }
+                    const assetContext = {
+                      matches,
+                      match,
+                      params: match.params,
+                      loaderData: match.loaderData,
+                    }
+                    const headFnContent =
+                      await route.options.head?.(assetContext)
+                    const meta = headFnContent?.meta
+                    const links = headFnContent?.links
+                    const headScripts = headFnContent?.scripts
+                    const styles = headFnContent?.styles
+
+                    const scripts = await route.options.scripts?.(assetContext)
+                    const headers = await route.options.headers?.(assetContext)
+                    return {
+                      meta,
+                      links,
+                      headScripts,
+                      headers,
+                      scripts,
+                      styles,
+                    }
+                  }
+
+                  const potentialPendingMinPromise = async () => {
+                    const latestMatch = this.getMatch(matchId)!
+                    if (latestMatch.minPendingPromise) {
+                      await latestMatch.minPendingPromise
+                    }
+                  }
 
                   const prevMatch = this.getMatch(matchId)!
+                  if (shouldSkipLoader(matchId)) {
+                    if (this.isServer) {
+                      const head = await executeHead()
+                      updateMatch(matchId, (prev) => ({
+                        ...prev,
+                        ...head,
+                      }))
+                      this.serverSsr?.onMatchSettled({
+                        router: this,
+                        match: this.getMatch(matchId)!,
+                      })
+                      return this.getMatch(matchId)!
+                    } else {
+                      await potentialPendingMinPromise()
+                    }
+                  }
                   // there is a loaderPromise, so we are in the middle of a load
-                  if (prevMatch.loaderPromise) {
+                  else if (prevMatch.loaderPromise) {
                     // do not block if we already have stale data we can show
                     // but only if the ongoing load is not a preload since error handling is different for preloads
                     // and we don't want to swallow errors
@@ -2367,7 +2547,6 @@ export class RouterCore<
                     }
                   } else {
                     const parentMatchPromise = matchPromises[index - 1] as any
-                    const route = this.looseRoutesById[routeId]!
 
                     const getLoaderContext = (): LoaderFnContext => {
                       const {
@@ -2426,39 +2605,6 @@ export class RouterCore<
                         !this.state.matches.find((d) => d.id === matchId),
                     }))
 
-                    const executeHead = async () => {
-                      const match = this.getMatch(matchId)
-                      // in case of a redirecting match during preload, the match does not exist
-                      if (!match) {
-                        return
-                      }
-                      const assetContext = {
-                        matches,
-                        match,
-                        params: match.params,
-                        loaderData: match.loaderData,
-                      }
-                      const headFnContent =
-                        await route.options.head?.(assetContext)
-                      const meta = headFnContent?.meta
-                      const links = headFnContent?.links
-                      const headScripts = headFnContent?.scripts
-                      const styles = headFnContent?.styles
-
-                      const scripts =
-                        await route.options.scripts?.(assetContext)
-                      const headers =
-                        await route.options.headers?.(assetContext)
-                      return {
-                        meta,
-                        links,
-                        headScripts,
-                        headers,
-                        scripts,
-                        styles,
-                      }
-                    }
-
                     const runLoader = async () => {
                       try {
                         // If the Matches component rendered
@@ -2466,17 +2612,16 @@ export class RouterCore<
                         // a minimum duration, we''ll wait for it to resolve
                         // before committing to the match and resolving
                         // the loadPromise
-                        const potentialPendingMinPromise = async () => {
-                          const latestMatch = this.getMatch(matchId)!
-
-                          if (latestMatch.minPendingPromise) {
-                            await latestMatch.minPendingPromise
-                          }
-                        }
 
                         // Actually run the loader and handle the result
                         try {
-                          this.loadRouteChunk(route)
+                          if (
+                            !this.isServer ||
+                            (this.isServer &&
+                              this.getMatch(matchId)!.ssr === true)
+                          ) {
+                            this.loadRouteChunk(route)
+                          }
 
                           updateMatch(matchId, (prev) => ({
                             ...prev,
@@ -2491,29 +2636,27 @@ export class RouterCore<
                             this.getMatch(matchId)!,
                             loaderData,
                           )
+                          updateMatch(matchId, (prev) => ({
+                            ...prev,
+                            loaderData,
+                          }))
 
                           // Lazy option can modify the route options,
                           // so we need to wait for it to resolve before
                           // we can use the options
                           await route._lazyPromise
-
+                          const head = await executeHead()
                           await potentialPendingMinPromise()
 
                           // Last but not least, wait for the the components
                           // to be preloaded before we resolve the match
                           await route._componentsPromise
-
                           updateMatch(matchId, (prev) => ({
                             ...prev,
                             error: undefined,
                             status: 'success',
                             isFetching: false,
                             updatedAt: Date.now(),
-                            loaderData,
-                          }))
-                          const head = await executeHead()
-                          updateMatch(matchId, (prev) => ({
-                            ...prev,
                             ...head,
                           }))
                         } catch (e) {
@@ -2559,13 +2702,18 @@ export class RouterCore<
                     }
 
                     // If the route is successful and still fresh, just resolve
-                    const { status, invalid } = this.getMatch(matchId)!
+                    const { status, invalid, _forcePending } =
+                      this.getMatch(matchId)!
                     loaderShouldRunAsync =
                       status === 'success' &&
                       (invalid || (shouldReload ?? age > staleAge))
                     if (preload && route.options.preload === false) {
                       // Do nothing
-                    } else if (loaderShouldRunAsync && !sync) {
+                    } else if (
+                      loaderShouldRunAsync &&
+                      !sync &&
+                      !_forcePending
+                    ) {
                       loaderIsRunningAsync = true
                       ;(async () => {
                         try {
@@ -2590,6 +2738,9 @@ export class RouterCore<
                     ) {
                       await runLoader()
                     } else {
+                      if (_forcePending) {
+                        await potentialPendingMinPromise()
+                      }
                       // if the loader did not run, still update head.
                       // reason: parent's beforeLoad may have changed the route context
                       // and only now do we know the route context (and that the loader would not run)
@@ -2598,6 +2749,10 @@ export class RouterCore<
                         ...prev,
                         ...head,
                       }))
+                      this.serverSsr?.onMatchSettled({
+                        router: this,
+                        match: this.getMatch(matchId)!,
+                      })
                     }
                   }
                   if (!loaderIsRunningAsync) {
@@ -2607,14 +2762,22 @@ export class RouterCore<
                     loadPromise?.resolve()
                   }
 
-                  updateMatch(matchId, (prev) => ({
-                    ...prev,
-                    isFetching: loaderIsRunningAsync ? prev.isFetching : false,
-                    loaderPromise: loaderIsRunningAsync
-                      ? prev.loaderPromise
-                      : undefined,
-                    invalid: false,
-                  }))
+                  updateMatch(matchId, (prev) => {
+                    clearTimeout(prev.pendingTimeout)
+                    return {
+                      ...prev,
+                      isFetching: loaderIsRunningAsync
+                        ? prev.isFetching
+                        : false,
+                      loaderPromise: loaderIsRunningAsync
+                        ? prev.loaderPromise
+                        : undefined,
+                      invalid: false,
+                      pendingTimeout: undefined,
+                      _dehydrated: undefined,
+                      _forcePending: undefined,
+                    }
+                  })
                   return this.getMatch(matchId)!
                 })(),
               )

package/src/ssr/ssr-client.ts

@@ -42,6 +42,7 @@ export interface SsrMatch {
   extracted?: Array<ClientExtractedEntry>
   updatedAt: MakeRouteMatch['updatedAt']
   status: MakeRouteMatch['status']
+  ssr?: boolean | 'data-only'
 }
 
 export type ClientExtractedEntry =
@@ -123,17 +124,36 @@ export async function hydrate(router: AnyRouter): Promise<any> {
 
   // Right after hydration and before the first render, we need to rehydrate each match
   // First step is to reyhdrate loaderData and __beforeLoadContext
+  let firstNonSsrMatchIndex: number | undefined = undefined
   matches.forEach((match) => {
     const dehydratedMatch = window.__TSR_SSR__!.matches.find(
       (d) => d.id === match.id,
     )
 
     if (!dehydratedMatch) {
+      Object.assign(match, { dehydrated: false, ssr: false })
       return
     }
 
     Object.assign(match, dehydratedMatch)
 
+    if (match.ssr === false) {
+      match._dehydrated = false
+    } else {
+      match._dehydrated = true
+    }
+
+    if (match.ssr === 'data-only' || match.ssr === false) {
+      if (firstNonSsrMatchIndex === undefined) {
+        firstNonSsrMatchIndex = match.index
+        match._forcePending = true
+      }
+    }
+
+    if (match.ssr === false) {
+      return
+    }
+
     // Handle beforeLoadContext
     if (dehydratedMatch.__beforeLoadContext) {
       match.__beforeLoadContext = router.ssr!.serializer.parse(
@@ -157,8 +177,6 @@ export async function hydrate(router: AnyRouter): Promise<any> {
     ;(match as unknown as SsrMatch).extracted?.forEach((ex) => {
       deepMutableSetByPath(match, ['loaderData', ...ex.path], ex.value)
     })
-
-    return match
   })
 
   router.__store.setState((s) => {
@@ -222,8 +240,36 @@ export async function hydrate(router: AnyRouter): Promise<any> {
     }),
   )
 
+  // schedule router.load() to run after the next tick so we can store the promise in the match before loading starts
+  const loadPromise = Promise.resolve()
+    .then(() => router.load())
+    .catch((err) => {
+      console.error('Error during router hydration:', err)
+    })
+
+  // in SPA mode we need to keep the outermost match  pending until router.load() is finished
+  // this will prevent that other pending components are rendered but hydration is not blocked
   if (matches[matches.length - 1]!.id !== lastMatchId) {
-    return await Promise.all([routeChunkPromise, router.load()])
+    const matchId = matches[0]!.id
+    router.updateMatch(matchId, (prev) => {
+      return {
+        ...prev,
+        _displayPending: true,
+        displayPendingPromise: loadPromise,
+        // make sure that the pending component is displayed for at least pendingMinMs
+        _forcePending: true,
+      }
+    })
+    // hide the pending component once the load is finished
+    loadPromise.then(() => {
+      router.updateMatch(matchId, (prev) => {
+        return {
+          ...prev,
+          _displayPending: undefined,
+          displayPendingPromise: undefined,
+        }
+      })
+    })
   }
 
   return routeChunkPromise

package/src/ssr/ssr-server.ts

@@ -190,6 +190,7 @@ export function onMatchSettled(opts: {
       extracted: extracted?.map((entry) => pick(entry, ['type', 'path'])),
       updatedAt: match.updatedAt,
       status: match.status,
+      ssr: match.ssr,
     } satisfies SsrMatch,
     {
       isScriptContext: true,

package/src/utils.ts

@@ -461,3 +461,15 @@ export function shallow<T>(objA: T, objB: T) {
   }
   return true
 }
+
+export function isModuleNotFoundError(error: any): boolean {
+  // chrome: "Failed to fetch dynamically imported module: http://localhost:5173/src/routes/posts.index.tsx?tsr-split"
+  // firefox: "error loading dynamically imported module: http://localhost:5173/src/routes/posts.index.tsx?tsr-split"
+  // safari: "Importing a module script failed."
+  if (typeof error?.message !== 'string') return false
+  return (
+    error.message.startsWith('Failed to fetch dynamically imported module') ||
+    error.message.startsWith('error loading dynamically imported module') ||
+    error.message.startsWith('Importing a module script failed')
+  )
+}