@tanstack/router-core 1.163.3 → 1.166.4

package/src/load-matches.ts

@@ -29,13 +29,13 @@ type InnerLoadContext = {
   firstBadMatchIndex?: number
   /** mutable state, scoped to a `loadMatches` call */
   rendered?: boolean
+  serialError?: unknown
   updateMatch: UpdateMatchFn
   matches: Array<AnyRouteMatch>
   preload?: boolean
+  forceStaleReload?: boolean
   onReady?: () => Promise<void>
   sync?: boolean
-  /** mutable state, scoped to a `loadMatches` call */
-  matchPromises: Array<Promise<AnyRouteMatch>>
 }
 
 const triggerOnReady = (inner: InnerLoadContext): void | Promise<void> => {
@@ -74,64 +74,45 @@ const buildMatchContext = (
   return context
 }
 
-const _handleNotFound = (
+const getNotFoundBoundaryIndex = (
   inner: InnerLoadContext,
   err: NotFoundError,
-  routerCode?: string,
-) => {
-  // Find the route that should handle the not found error
-  // First check if a specific route is requested to show the error
-  const routeCursor =
-    inner.router.routesById[err.routeId ?? ''] ?? inner.router.routeTree
-
-  // Ensure a NotFoundComponent exists on the route
-  if (
-    !routeCursor.options.notFoundComponent &&
-    (inner.router.options as any)?.defaultNotFoundComponent
-  ) {
-    routeCursor.options.notFoundComponent = (
-      inner.router.options as any
-    ).defaultNotFoundComponent
-  }
-
-  // For BEFORE_LOAD errors that will walk up to a parent route,
-  // don't require notFoundComponent on the current (child) route —
-  // an ancestor will handle it. Only enforce the invariant when
-  // we've reached a route that won't walk up further.
-  const willWalkUp = routerCode === 'BEFORE_LOAD' && routeCursor.parentRoute
-
-  if (!willWalkUp) {
-    // Ensure we have a notFoundComponent
-    invariant(
-      routeCursor.options.notFoundComponent,
-      'No notFoundComponent found. Please set a notFoundComponent on your route or provide a defaultNotFoundComponent to the router.',
-    )
+): number | undefined => {
+  if (!inner.matches.length) {
+    return undefined
   }
 
-  // Find the match for this route
-  const matchForRoute = inner.matches.find((m) => m.routeId === routeCursor.id)
+  const requestedRouteId = err.routeId
+  const matchedRootIndex = inner.matches.findIndex(
+    (m) => m.routeId === inner.router.routeTree.id,
+  )
+  const rootIndex = matchedRootIndex >= 0 ? matchedRootIndex : 0
 
-  invariant(matchForRoute, 'Could not find match for route: ' + routeCursor.id)
+  let startIndex = requestedRouteId
+    ? inner.matches.findIndex((match) => match.routeId === requestedRouteId)
+    : (inner.firstBadMatchIndex ?? inner.matches.length - 1)
 
-  // Assign the error to the match - using non-null assertion since we've checked with invariant
-  inner.updateMatch(matchForRoute.id, (prev) => ({
-    ...prev,
-    status: 'notFound',
-    error: err,
-    isFetching: false,
-  }))
+  if (startIndex < 0) {
+    startIndex = rootIndex
+  }
 
-  if (willWalkUp) {
-    err.routeId = routeCursor.parentRoute!.id
-    _handleNotFound(inner, err, routerCode)
+  for (let i = startIndex; i >= 0; i--) {
+    const match = inner.matches[i]!
+    const route = inner.router.looseRoutesById[match.routeId]!
+    if (route.options.notFoundComponent) {
+      return i
+    }
   }
+
+  // If no boundary component is found, preserve explicit routeId targeting behavior,
+  // otherwise default to root for untargeted notFounds.
+  return requestedRouteId ? startIndex : rootIndex
 }
 
 const handleRedirectAndNotFound = (
   inner: InnerLoadContext,
   match: AnyRouteMatch | undefined,
   err: unknown,
-  routerCode?: string,
 ): void => {
   if (!isRedirect(err) && !isNotFound(err)) return
 
@@ -146,19 +127,26 @@ const handleRedirectAndNotFound = (
     match._nonReactive.beforeLoadPromise = undefined
     match._nonReactive.loaderPromise = undefined
 
-    const status = isRedirect(err) ? 'redirected' : 'notFound'
-
     match._nonReactive.error = err
 
     inner.updateMatch(match.id, (prev) => ({
       ...prev,
-      status,
+      status: isRedirect(err)
+        ? 'redirected'
+        : prev.status === 'pending'
+          ? 'success'
+          : prev.status,
       context: buildMatchContext(inner, match.index),
       isFetching: false,
       error: err,
     }))
 
     if (isNotFound(err) && !err.routeId) {
+      // Stamp the throwing match's routeId so that the finalization step in
+      // loadMatches knows where the notFound originated.  The actual boundary
+      // resolution (walking up to the nearest notFoundComponent) is deferred to
+      // the finalization step, where firstBadMatchIndex is stable and
+      // headMaxIndex can be capped correctly.
       err.routeId = match.routeId
     }
 
@@ -170,18 +158,19 @@ const handleRedirectAndNotFound = (
     err.options._fromLocation = inner.location
     err.redirectHandled = true
     err = inner.router.resolveRedirect(err)
-    throw err
-  } else {
-    _handleNotFound(inner, err, routerCode)
-    throw err
   }
+
+  throw err
 }
 
 const shouldSkipLoader = (
   inner: InnerLoadContext,
   matchId: string,
 ): boolean => {
-  const match = inner.router.getMatch(matchId)!
+  const match = inner.router.getMatch(matchId)
+  if (!match) {
+    return true
+  }
   // upon hydration, we skip the loader if the match has been dehydrated on the server
   if (!(isServer ?? inner.router.isServer) && match._nonReactive.dehydrated) {
     return true
@@ -194,6 +183,21 @@ const shouldSkipLoader = (
   return false
 }
 
+const syncMatchContext = (
+  inner: InnerLoadContext,
+  matchId: string,
+  index: number,
+): void => {
+  const nextContext = buildMatchContext(inner, index)
+
+  inner.updateMatch(matchId, (prev) => {
+    return {
+      ...prev,
+      context: nextContext,
+    }
+  })
+}
+
 const handleSerialError = (
   inner: InnerLoadContext,
   index: number,
@@ -212,23 +216,13 @@ const handleSerialError = (
 
   err.routerCode = routerCode
   inner.firstBadMatchIndex ??= index
-  handleRedirectAndNotFound(
-    inner,
-    inner.router.getMatch(matchId),
-    err,
-    routerCode,
-  )
+  handleRedirectAndNotFound(inner, inner.router.getMatch(matchId), err)
 
   try {
     route.options.onError?.(err)
   } catch (errorHandlerErr) {
     err = errorHandlerErr
-    handleRedirectAndNotFound(
-      inner,
-      inner.router.getMatch(matchId),
-      err,
-      routerCode,
-    )
+    handleRedirectAndNotFound(inner, inner.router.getMatch(matchId), err)
   }
 
   inner.updateMatch(matchId, (prev) => {
@@ -245,6 +239,10 @@ const handleSerialError = (
       abortController: new AbortController(),
     }
   })
+
+  if (!inner.preload && !isRedirect(err) && !isNotFound(err)) {
+    inner.serialError ??= err
+  }
 }
 
 const isBeforeLoadSsr = (
@@ -500,8 +498,6 @@ const executeBeforeLoad = (
 
     batch(() => {
       pending()
-      // Only store __beforeLoadContext here, don't update context yet
-      // Context will be updated in loadRouteMatch after loader completes
       inner.updateMatch(matchId, (prev) => ({
         ...prev,
         __beforeLoadContext: beforeLoadContext,
@@ -606,11 +602,12 @@ const executeHead = (
 
 const getLoaderContext = (
   inner: InnerLoadContext,
+  matchPromises: Array<Promise<AnyRouteMatch>>,
   matchId: string,
   index: number,
   route: AnyRoute,
 ): LoaderFnContext => {
-  const parentMatchPromise = inner.matchPromises[index - 1] as any
+  const parentMatchPromise = matchPromises[index - 1] as any
   const { params, loaderDeps, abortController, cause } =
     inner.router.getMatch(matchId)!
 
@@ -639,6 +636,7 @@ const getLoaderContext = (
 
 const runLoader = async (
   inner: InnerLoadContext,
+  matchPromises: Array<Promise<AnyRouteMatch>>,
   matchId: string,
   index: number,
   route: AnyRoute,
@@ -660,7 +658,7 @@ const runLoader = async (
 
       // Kick off the loader!
       const loaderResult = route.options.loader?.(
-        getLoaderContext(inner, matchId, index, route),
+        getLoaderContext(inner, matchPromises, matchId, index, route),
       )
       const loaderResultIsPromise =
         route.options.loader && isPromise(loaderResult)
@@ -775,11 +773,13 @@ const runLoader = async (
 
 const loadRouteMatch = async (
   inner: InnerLoadContext,
+  matchPromises: Array<Promise<AnyRouteMatch>>,
   index: number,
 ): Promise<AnyRouteMatch> => {
   async function handleLoader(
     preload: boolean,
     prevMatch: AnyRouteMatch,
+    previousRouteMatchId: string | undefined,
     match: AnyRouteMatch,
     route: AnyRoute,
   ) {
@@ -798,20 +798,29 @@ const loadRouteMatch = async (
     // if provided.
     const shouldReload =
       typeof shouldReloadOption === 'function'
-        ? shouldReloadOption(getLoaderContext(inner, matchId, index, route))
+        ? shouldReloadOption(
+            getLoaderContext(inner, matchPromises, matchId, index, route),
+          )
         : shouldReloadOption
 
     // If the route is successful and still fresh, just resolve
     const { status, invalid } = match
+    const staleMatchShouldReload =
+      age > staleAge &&
+      (!!inner.forceStaleReload ||
+        match.cause === 'enter' ||
+        (previousRouteMatchId !== undefined &&
+          previousRouteMatchId !== match.id))
     loaderShouldRunAsync =
-      status === 'success' && (invalid || (shouldReload ?? age > staleAge))
+      status === 'success' &&
+      (invalid || (shouldReload ?? staleMatchShouldReload))
     if (preload && route.options.preload === false) {
       // Do nothing
     } else if (loaderShouldRunAsync && !inner.sync) {
       loaderIsRunningAsync = true
       ;(async () => {
         try {
-          await runLoader(inner, matchId, index, route)
+          await runLoader(inner, matchPromises, matchId, index, route)
           const match = inner.router.getMatch(matchId)!
           match._nonReactive.loaderPromise?.resolve()
           match._nonReactive.loadPromise?.resolve()
@@ -823,7 +832,9 @@ const loadRouteMatch = async (
         }
       })()
     } else if (status !== 'success' || (loaderShouldRunAsync && inner.sync)) {
-      await runLoader(inner, matchId, index, route)
+      await runLoader(inner, matchPromises, matchId, index, route)
+    } else {
+      syncMatchContext(inner, matchId, index)
     }
   }
 
@@ -833,11 +844,22 @@ const loadRouteMatch = async (
   const route = inner.router.looseRoutesById[routeId]!
 
   if (shouldSkipLoader(inner, matchId)) {
+    const match = inner.router.getMatch(matchId)
+    if (!match) {
+      return inner.matches[index]!
+    }
+
+    syncMatchContext(inner, matchId, index)
+
     if (isServer ?? inner.router.isServer) {
       return inner.router.getMatch(matchId)!
     }
   } else {
     const prevMatch = inner.router.getMatch(matchId)! // This is where all of the stale-while-revalidate magic happens
+    const previousRouteMatchId =
+      inner.router.state.matches[index]?.routeId === routeId
+        ? inner.router.state.matches[index]!.id
+        : inner.router.state.matches.find((d) => d.routeId === routeId)?.id
     const preload = resolvePreload(inner, matchId)
 
     // there is a loaderPromise, so we are in the middle of a load
@@ -856,7 +878,13 @@ const loadRouteMatch = async (
       }
 
       if (match.status === 'pending') {
-        await handleLoader(preload, prevMatch, match, route)
+        await handleLoader(
+          preload,
+          prevMatch,
+          previousRouteMatchId,
+          match,
+          route,
+        )
       }
     } else {
       const nextPreload =
@@ -870,7 +898,7 @@ const loadRouteMatch = async (
         }))
       }
 
-      await handleLoader(preload, prevMatch, match, route)
+      await handleLoader(preload, prevMatch, previousRouteMatchId, match, route)
     }
   }
   const match = inner.router.getMatch(matchId)!
@@ -902,13 +930,13 @@ export async function loadMatches(arg: {
   location: ParsedLocation
   matches: Array<AnyRouteMatch>
   preload?: boolean
+  forceStaleReload?: boolean
   onReady?: () => Promise<void>
   updateMatch: UpdateMatchFn
   sync?: boolean
 }): Promise<Array<MakeRouteMatch>> {
-  const inner: InnerLoadContext = Object.assign(arg, {
-    matchPromises: [],
-  })
+  const inner: InnerLoadContext = arg
+  const matchPromises: Array<Promise<AnyRouteMatch>> = []
 
   // 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
@@ -919,77 +947,201 @@ export async function loadMatches(arg: {
     triggerOnReady(inner)
   }
 
-  try {
-    // Execute all beforeLoads one by one
-    for (let i = 0; i < inner.matches.length; i++) {
+  let beforeLoadNotFound: NotFoundError | undefined
+
+  // Execute all beforeLoads one by one
+  for (let i = 0; i < inner.matches.length; i++) {
+    try {
       const beforeLoad = handleBeforeLoad(inner, i)
       if (isPromise(beforeLoad)) await beforeLoad
+    } catch (err) {
+      if (isRedirect(err)) {
+        throw err
+      }
+      if (isNotFound(err)) {
+        beforeLoadNotFound = err
+      } else {
+        if (!inner.preload) throw err
+      }
+      break
     }
 
-    // Execute all loaders in parallel
-    const max = inner.firstBadMatchIndex ?? inner.matches.length
-    for (let i = 0; i < max; i++) {
-      inner.matchPromises.push(loadRouteMatch(inner, i))
+    if (inner.serialError) {
+      break
     }
-    // Use allSettled to ensure all loaders complete regardless of success/failure
-    const results = await Promise.allSettled(inner.matchPromises)
-
-    const failures = results
-      // TODO when we drop support for TS 5.4, we can use the built-in type guard for PromiseRejectedResult
-      .filter(
-        (result): result is PromiseRejectedResult =>
-          result.status === 'rejected',
-      )
-      .map((result) => result.reason)
+  }
 
-    // Find first redirect (throw immediately) or notFound (throw after head execution)
-    let firstNotFound: unknown
-    for (const err of failures) {
-      if (isRedirect(err)) {
-        throw err
+  // Execute loaders once, with max index adapted for beforeLoad notFound handling.
+  const baseMaxIndexExclusive = inner.firstBadMatchIndex ?? inner.matches.length
+
+  const boundaryIndex =
+    beforeLoadNotFound && !inner.preload
+      ? getNotFoundBoundaryIndex(inner, beforeLoadNotFound)
+      : undefined
+
+  const maxIndexExclusive =
+    beforeLoadNotFound && inner.preload
+      ? 0
+      : boundaryIndex !== undefined
+        ? Math.min(boundaryIndex + 1, baseMaxIndexExclusive)
+        : baseMaxIndexExclusive
+
+  let firstNotFound: NotFoundError | undefined
+  let firstUnhandledRejection: unknown
+
+  for (let i = 0; i < maxIndexExclusive; i++) {
+    matchPromises.push(loadRouteMatch(inner, matchPromises, i))
+  }
+
+  try {
+    await Promise.all(matchPromises)
+  } catch {
+    const settled = await Promise.allSettled(matchPromises)
+
+    for (const result of settled) {
+      if (result.status !== 'rejected') continue
+
+      const reason = result.reason
+      if (isRedirect(reason)) {
+        throw reason
       }
-      if (!firstNotFound && isNotFound(err)) {
-        firstNotFound = err
+      if (isNotFound(reason)) {
+        firstNotFound ??= reason
+      } else {
+        firstUnhandledRejection ??= reason
       }
     }
 
-    // serially execute head functions after all loaders have completed (successfully or not)
-    // Each head execution is wrapped in try-catch to ensure all heads run even if one fails
-    for (const match of inner.matches) {
-      const { id: matchId, routeId } = match
-      const route = inner.router.looseRoutesById[routeId]!
-      try {
-        const headResult = executeHead(inner, matchId, route)
-        if (headResult) {
-          const head = await headResult
-          inner.updateMatch(matchId, (prev) => ({
-            ...prev,
-            ...head,
-          }))
-        }
-      } catch (err) {
-        // Log error but continue executing other head functions
-        console.error(`Error executing head for route ${routeId}:`, err)
-      }
+    if (firstUnhandledRejection !== undefined) {
+      throw firstUnhandledRejection
     }
+  }
+
+  const notFoundToThrow =
+    firstNotFound ??
+    (beforeLoadNotFound && !inner.preload ? beforeLoadNotFound : undefined)
+
+  let headMaxIndex = inner.serialError
+    ? (inner.firstBadMatchIndex ?? 0)
+    : inner.matches.length - 1
+
+  if (!notFoundToThrow && beforeLoadNotFound && inner.preload) {
+    return inner.matches
+  }
+
+  if (notFoundToThrow) {
+    // Determine once which matched route will actually render the
+    // notFoundComponent, then pass this precomputed index through the remaining
+    // finalization steps.
+    // This can differ from the throwing route when routeId targets an ancestor
+    // boundary (or when bubbling resolves to a parent/root boundary).
+    const renderedBoundaryIndex = getNotFoundBoundaryIndex(
+      inner,
+      notFoundToThrow,
+    )
+
+    invariant(
+      renderedBoundaryIndex !== undefined,
+      'Could not find match for notFound boundary',
+    )
+    const boundaryMatch = inner.matches[renderedBoundaryIndex]!
 
-    // Throw notFound after head execution
-    if (firstNotFound) {
-      throw firstNotFound
+    const boundaryRoute = inner.router.looseRoutesById[boundaryMatch.routeId]!
+    const defaultNotFoundComponent = (inner.router.options as any)
+      ?.defaultNotFoundComponent
+
+    // Ensure a notFoundComponent exists on the boundary route
+    if (!boundaryRoute.options.notFoundComponent && defaultNotFoundComponent) {
+      boundaryRoute.options.notFoundComponent = defaultNotFoundComponent
     }
 
-    const readyPromise = triggerOnReady(inner)
-    if (isPromise(readyPromise)) await readyPromise
-  } catch (err) {
-    if (isNotFound(err) && !inner.preload) {
-      const readyPromise = triggerOnReady(inner)
-      if (isPromise(readyPromise)) await readyPromise
-      throw err
+    notFoundToThrow.routeId = boundaryMatch.routeId
+
+    const boundaryIsRoot = boundaryMatch.routeId === inner.router.routeTree.id
+
+    inner.updateMatch(boundaryMatch.id, (prev) => ({
+      ...prev,
+      ...(boundaryIsRoot
+        ? // For root boundary, use globalNotFound so the root component's
+          // shell still renders and <Outlet> handles the not-found display,
+          // instead of replacing the entire root shell via status='notFound'.
+          { status: 'success' as const, globalNotFound: true, error: undefined }
+        : // For non-root boundaries, set status:'notFound' so MatchInner
+          // renders the notFoundComponent directly.
+          { status: 'notFound' as const, error: notFoundToThrow }),
+      isFetching: false,
+    }))
+
+    headMaxIndex = renderedBoundaryIndex
+
+    // Ensure the rendering boundary route chunk (and its lazy components, including
+    // lazy notFoundComponent) is loaded before we continue to head execution/render.
+    await loadRouteChunk(boundaryRoute)
+  } else if (!inner.preload) {
+    // Clear stale root global-not-found state on normal navigations that do not
+    // throw notFound. This must live here (instead of only in runLoader success)
+    // because the root loader may be skipped when data is still fresh.
+    const rootMatch = inner.matches[0]!
+    // `rootMatch` is the next match for this navigation. If it is not global
+    // not-found, then any currently stored root global-not-found is stale.
+    if (!rootMatch.globalNotFound) {
+      // `currentRootMatch` is the current store state (from the previous
+      // navigation/load). Update only when a stale flag is actually present.
+      const currentRootMatch = inner.router.getMatch(rootMatch.id)
+      if (currentRootMatch?.globalNotFound) {
+        inner.updateMatch(rootMatch.id, (prev) => ({
+          ...prev,
+          globalNotFound: false,
+          error: undefined,
+        }))
+      }
     }
-    if (isRedirect(err)) {
-      throw err
+  }
+
+  // When a serial error occurred (e.g. beforeLoad threw a regular Error),
+  // the erroring route's lazy chunk wasn't loaded because loaders were skipped.
+  // We need to load it so the code-split errorComponent is available for rendering.
+  if (inner.serialError && inner.firstBadMatchIndex !== undefined) {
+    const errorRoute =
+      inner.router.looseRoutesById[
+        inner.matches[inner.firstBadMatchIndex]!.routeId
+      ]!
+    await loadRouteChunk(errorRoute)
+  }
+
+  // serially execute heads once after loaders/notFound handling, ensuring
+  // all head functions get a chance even if one throws.
+  for (let i = 0; i <= headMaxIndex; i++) {
+    const match = inner.matches[i]!
+    const { id: matchId, routeId } = match
+    const route = inner.router.looseRoutesById[routeId]!
+    try {
+      const headResult = executeHead(inner, matchId, route)
+      if (headResult) {
+        const head = await headResult
+        inner.updateMatch(matchId, (prev) => ({
+          ...prev,
+          ...head,
+        }))
+      }
+    } catch (err) {
+      console.error(`Error executing head for route ${routeId}:`, err)
     }
   }
+
+  const readyPromise = triggerOnReady(inner)
+  if (isPromise(readyPromise)) {
+    await readyPromise
+  }
+
+  if (notFoundToThrow) {
+    throw notFoundToThrow
+  }
+
+  if (inner.serialError && !inner.preload && !inner.onReady) {
+    throw inner.serialError
+  }
+
   return inner.matches
 }
 

package/src/router.ts

@@ -2364,6 +2364,7 @@ export class RouterCore<
     let redirect: AnyRedirect | undefined
     let notFound: NotFoundError | undefined
     let loadPromise: Promise<void>
+    const previousLocation = this.state.resolvedLocation ?? this.state.location
 
     // eslint-disable-next-line prefer-const
     loadPromise = new Promise<void>((resolve) => {
@@ -2394,6 +2395,7 @@ export class RouterCore<
           await loadMatches({
             router: this,
             sync: opts?.sync,
+            forceStaleReload: previousLocation.href === next.href,
             matches: this.state.pendingMatches as Array<AnyRouteMatch>,
             location: next,
             updateMatch: this.updateMatch,