@tanstack/react-router 1.13.0 → 1.14.0

package/src/Matches.tsx

@@ -11,6 +11,7 @@ import {
   RootSearchSchema,
   StaticDataRouteOption,
   UpdatableStaticRouteOption,
+  rootRouteId,
 } from './route'
 import {
   AllParams,
@@ -23,6 +24,12 @@ import {
 } from './routeInfo'
 import { RegisteredRouter, RouterState } from './router'
 import { DeepOptional, Expand, NoInfer, StrictOrFrom, pick } from './utils'
+import {
+  CatchNotFound,
+  DefaultGlobalNotFound,
+  NotFoundError,
+  isNotFound,
+} from './not-found'
 
 export const matchContext = React.createContext<string | undefined>(undefined)
 
@@ -66,6 +73,7 @@ export interface RouteMatch<
   meta?: JSX.IntrinsicElements['meta'][]
   links?: JSX.IntrinsicElements['link'][]
   scripts?: JSX.IntrinsicElements['script'][]
+  notFoundError?: NotFoundError
   staticData: StaticDataRouteOption
 }
 
@@ -125,6 +133,12 @@ export function Match({ matchId }: { matchId: string }) {
     router.options.defaultErrorComponent ??
     ErrorComponent
 
+  const routeNotFoundComponent = route.isRoot
+    ? // If it's the root route, use the globalNotFound option, with fallback to the notFoundRoute's component
+      route.options.notFoundComponent ??
+      router.options.notFoundRoute?.options.component
+    : route.options.notFoundComponent
+
   const ResolvedSuspenseBoundary =
     route.options.wrapInSuspense ??
     PendingComponent ??
@@ -138,17 +152,35 @@ export function Match({ matchId }: { matchId: string }) {
     ? CatchBoundary
     : SafeFragment
 
+  const ResolvedNotFoundBoundary = routeNotFoundComponent
+    ? CatchNotFound
+    : SafeFragment
+
   return (
     <matchContext.Provider value={matchId}>
       <ResolvedSuspenseBoundary fallback={pendingElement}>
         <ResolvedCatchBoundary
           getResetKey={() => router.state.resolvedLocation.state?.key}
           errorComponent={routeErrorComponent}
-          onCatch={() => {
+          onCatch={(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: ${matchId}`)
           }}
         >
-          <MatchInner matchId={matchId!} pendingElement={pendingElement} />
+          <ResolvedNotFoundBoundary
+            fallback={(error) => {
+              // If the current not found handler doesn't exist or doesn't handle global not founds, forward it up the tree
+              if (!routeNotFoundComponent || (error.global && !route.isRoot))
+                throw error
+
+              return React.createElement(routeNotFoundComponent, {
+                data: error.data,
+              })
+            }}
+          >
+            <MatchInner matchId={matchId!} pendingElement={pendingElement} />
+          </ResolvedNotFoundBoundary>
         </ResolvedCatchBoundary>
       </ResolvedSuspenseBoundary>
     </matchContext.Provider>
@@ -170,16 +202,31 @@ function MatchInner({
 
   const route = router.routesById[routeId]!
 
-  const match = useRouterState({
-    select: (s) =>
-      pick(getRenderedMatches(s).find((d) => d.id === matchId)!, [
+  const { match } = useRouterState({
+    select: (s) => ({
+      match: pick(getRenderedMatches(s).find((d) => d.id === matchId)!, [
         'status',
         'error',
         'showPending',
         'loadPromise',
+        'notFoundError',
       ]),
+    }),
   })
 
+  // If a global not-found is found, and it's the root route, render the global not-found component.
+  if (match.notFoundError) {
+    if (routeId === rootRouteId && !route.options.notFoundComponent)
+      return <DefaultGlobalNotFound />
+
+    invariant(
+      route.options.notFoundComponent,
+      'Route matched with notFoundError should have a notFoundComponent',
+    )
+
+    return <route.options.notFoundComponent data={match.notFoundError} />
+  }
+
   if (match.status === 'error') {
     if (isServerSideError(match.error)) {
       const deserializeError =

package/src/fileRoute.ts

@@ -85,12 +85,11 @@ export type ResolveFilePath<
 export type FileRoutePath<
   TParentRoute extends AnyRoute,
   TFilePath extends string,
-> =
-  ResolveFilePath<TParentRoute, TFilePath> extends `_${infer _}`
+> = ResolveFilePath<TParentRoute, TFilePath> extends `_${infer _}`
+  ? ''
+  : ResolveFilePath<TParentRoute, TFilePath> extends `/_${infer _}`
     ? ''
-    : ResolveFilePath<TParentRoute, TFilePath> extends `/_${infer _}`
-      ? ''
-      : ResolveFilePath<TParentRoute, TFilePath>
+    : ResolveFilePath<TParentRoute, TFilePath>
 
 export function createFileRoute<
   TFilePath extends keyof FileRoutesByPath,
@@ -268,7 +267,7 @@ export function FileRouteLoader<
 
 export type LazyRouteOptions = Pick<
   UpdatableRouteOptions<AnySearchSchema, any>,
-  'component' | 'errorComponent' | 'pendingComponent'
+  'component' | 'errorComponent' | 'pendingComponent' | 'notFoundComponent'
 >
 
 export class LazyRoute<TRoute extends AnyRoute> {

package/src/index.tsx

@@ -29,3 +29,4 @@ export * from './useRouteContext'
 export * from './useRouter'
 export * from './useRouterState'
 export * from './utils'
+export * from './not-found'

package/src/not-found.tsx

@@ -0,0 +1,54 @@
+import * as React from 'react'
+import { CatchBoundary } from './CatchBoundary'
+import { useRouterState } from './useRouterState'
+import { RegisteredRouter, RouteIds } from '.'
+
+export type NotFoundError = {
+  global?: boolean
+  data?: any
+  throw?: boolean
+  route?: RouteIds<RegisteredRouter['routeTree']>
+}
+
+export function notFound(options: NotFoundError = {}) {
+  ;(options as any).isNotFound = true
+  if (options.throw) throw options
+  return options
+}
+
+export function isNotFound(obj: any): obj is NotFoundError {
+  return !!obj?.isNotFound
+}
+
+export function CatchNotFound(props: {
+  fallback?: (error: NotFoundError) => React.ReactElement
+  onCatch?: (error: any) => void
+  children: React.ReactNode
+}) {
+  // TODO: Some way for the user to programmatically reset the not-found boundary?
+  const resetKey = useRouterState({
+    select: (s) => `not-found-${s.location.pathname}-${s.status}`,
+  })
+
+  return (
+    <CatchBoundary
+      getResetKey={() => resetKey}
+      onCatch={(error) => {
+        if (isNotFound(error)) {
+          props.onCatch?.(error)
+        } else {
+          throw error
+        }
+      }}
+      errorComponent={({ error }: { error: NotFoundError }) =>
+        props.fallback?.(error)
+      }
+    >
+      {props.children}
+    </CatchBoundary>
+  )
+}
+
+export function DefaultGlobalNotFound() {
+  return <p>Not Found</p>
+}

package/src/route.ts

@@ -19,6 +19,8 @@ import {
 } from './utils'
 import { BuildLocationFn, NavigateFn } from './RouterProvider'
 import { LazyRoute } from '.'
+import warning from 'tiny-warning'
+import { NotFoundError, notFound } from '.'
 
 export const rootRouteId = '__root__' as const
 export type RootRouteId = typeof rootRouteId
@@ -191,6 +193,7 @@ export type UpdatableRouteOptions<
   // The content to be rendered when the route is matched. If no component is provided, defaults to `<Outlet />`
   component?: RouteComponent
   errorComponent?: false | null | ErrorRouteComponent
+  notFoundComponent?: NotFoundRouteComponent
   pendingComponent?: RouteComponent
   pendingMs?: number
   pendingMinMs?: number
@@ -368,12 +371,11 @@ export type MergeFromFromParent<T, U> = IsAny<T, U, T & U>
 export type ResolveAllParams<
   TParentRoute extends AnyRoute,
   TParams extends AnyPathParams,
-> =
-  Record<never, string> extends TParentRoute['types']['allParams']
-    ? TParams
-    : Expand<
-        UnionToIntersection<TParentRoute['types']['allParams'] & TParams> & {}
-      >
+> = Record<never, string> extends TParentRoute['types']['allParams']
+  ? TParams
+  : Expand<
+      UnionToIntersection<TParentRoute['types']['allParams'] & TParams> & {}
+    >
 
 export type RouteConstraints = {
   TParentRoute: AnyRoute
@@ -573,6 +575,10 @@ export class RouteApi<
   }): TSelected => {
     return useLoaderData({ ...opts, from: this.id } as any)
   }
+
+  notFound = (opts?: NotFoundError) => {
+    return notFound({ route: this.id as string, ...opts })
+  }
 }
 
 /**
@@ -1249,6 +1255,10 @@ export type ErrorComponentProps = {
   error: unknown
   info: { componentStack: string }
 }
+export type NotFoundRouteProps = {
+  // TODO: Make sure this is `| null | undefined` (this is for global not-founds)
+  data: unknown
+}
 //
 
 export type ReactNode = any
@@ -1266,6 +1276,8 @@ export type RouteComponent<TProps = any> = SyncRouteComponent<TProps> &
 
 export type ErrorRouteComponent = RouteComponent<ErrorComponentProps>
 
+export type NotFoundRouteComponent = SyncRouteComponent<NotFoundRouteProps>
+
 export class NotFoundRoute<
   TParentRoute extends AnyRootRoute,
   TSearchSchemaInput extends Record<string, any> = {},

package/src/router.ts

@@ -17,6 +17,7 @@ import {
   RouteMask,
   Route,
   LoaderFnContext,
+  rootRouteId,
 } from './route'
 import {
   FullSearchSchema,
@@ -63,6 +64,7 @@ import {
 } from './path'
 import invariant from 'tiny-invariant'
 import { isRedirect } from './redirects'
+import { NotFoundError, isNotFound } from './not-found'
 import { ResolveRelativePath, ToOptions } from './link'
 import { NoInfer } from '@tanstack/react-store'
 // import warning from 'tiny-warning'
@@ -131,9 +133,15 @@ export interface RouterOptions<
   unmaskOnReload?: boolean
   Wrap?: (props: { children: any }) => JSX.Element
   InnerWrap?: (props: { children: any }) => JSX.Element
+  /**
+   * @deprecated
+   * Use `notFoundComponent` instead.
+   * See https://tanstack.com/router/v1/docs/guide/not-found-errors#migrating-from-notfoundroute for more info.
+   */
   notFoundRoute?: AnyRoute
   transformer?: RouterTransformer
   errorSerializer?: RouterErrorSerializer<TSerializedError>
+  globalNotFound?: RouteComponent
 }
 
 export interface RouterTransformer {
@@ -182,7 +190,7 @@ export interface DehydratedRouterState {
 
 export type DehydratedRouteMatch = Pick<
   RouteMatch,
-  'id' | 'status' | 'updatedAt' | 'loaderData'
+  'id' | 'status' | 'updatedAt' | 'notFoundError' | 'loaderData'
 >
 
 export interface DehydratedRouter {
@@ -200,6 +208,7 @@ export const componentTypes = [
   'component',
   'errorComponent',
   'pendingComponent',
+  'notFoundComponent',
 ] as const
 
 export type RouterEvents = {
@@ -309,6 +318,12 @@ export class Router<
       TSerializedError
     >,
   ) => {
+    if (newOptions.notFoundRoute) {
+      console.warn(
+        'The notFoundRoute API is deprecated and will be removed in the next major version. See https://tanstack.com/router/v1/docs/guide/not-found-errors#migrating-from-notfoundroute for more info.',
+      )
+    }
+
     const previousOptions = this.options
     this.options = {
       ...this.options,
@@ -593,17 +608,23 @@ export class Router<
 
     let matchedRoutes: AnyRoute[] = [routeCursor]
 
+    let isGlobalNotFound = false
+
     // Check to see if the route needs a 404 entry
     if (
       // If we found a route, and it's not an index route and we have left over path
-      (foundRoute
+      foundRoute
         ? foundRoute.path !== '/' && routeParams['**']
         : // Or if we didn't find a route and we have left over path
-          trimPathRight(pathname)) &&
-      // And we have a 404 route configured
-      this.options.notFoundRoute
+          trimPathRight(pathname)
     ) {
-      matchedRoutes.push(this.options.notFoundRoute)
+      // If the user has defined an (old) 404 route, use it
+      if (this.options.notFoundRoute) {
+        matchedRoutes.push(this.options.notFoundRoute)
+      } else {
+        // If there is no routes found during path matching
+        isGlobalNotFound = true
+      }
     }
 
     while (routeCursor?.parentRoute) {
@@ -722,7 +743,14 @@ export class Router<
       )
 
       const match: AnyRouteMatch = existingMatch
-        ? { ...existingMatch, cause }
+        ? {
+            ...existingMatch,
+            cause,
+            notFoundError:
+              isGlobalNotFound && route.id === rootRouteId
+                ? { global: true }
+                : undefined,
+          }
         : {
             id: matchId,
             routeId: route.id,
@@ -745,6 +773,10 @@ export class Router<
             loaderDeps,
             invalid: false,
             preload: false,
+            notFoundError:
+              isGlobalNotFound && route.id === rootRouteId
+                ? { global: true }
+                : undefined,
             links: route.options.links?.(),
             scripts: route.options.scripts?.(),
             staticData: route.options.staticData || {},
@@ -793,8 +825,8 @@ export class Router<
         this.latestLocation.pathname,
         fromSearch,
       )
-      const stayingMatches = matches?.filter((d) =>
-        fromMatches?.find((e) => e.routeId === d.routeId),
+      const stayingMatches = matches?.filter(
+        (d) => fromMatches?.find((e) => e.routeId === d.routeId),
       )
 
       const prevParams = { ...last(fromMatches)?.params }
@@ -1110,6 +1142,10 @@ export class Router<
             throw err
           }
 
+          if (isNotFound(err)) {
+            this.updateMatchesWithNotFound(matches, match, err)
+          }
+
           try {
             route.options.onError?.(err)
           } catch (errorHandlerErr) {
@@ -1212,6 +1248,11 @@ export class Router<
               }
               return true
             }
+
+            if (isNotFound(err)) {
+              this.updateMatchesWithNotFound(matches, match, err)
+            }
+
             return false
           }
 
@@ -1708,7 +1749,15 @@ export class Router<
     return {
       state: {
         dehydratedMatches: this.state.matches.map((d) => ({
-          ...pick(d, ['id', 'status', 'updatedAt', 'loaderData']),
+          ...pick(d, [
+            'id',
+            'status',
+            'updatedAt',
+            'loaderData',
+            // Not-founds that occur during SSR don't require the client to load data before
+            // triggering in order to prevent the flicker of the loading component
+            'notFoundError',
+          ]),
           // If an error occurs server-side during SSRing,
           // send a small subset of the error to the client
           error: d.error
@@ -1777,6 +1826,46 @@ export class Router<
     })
   }
 
+  // Finds a match that has a notFoundComponent
+  updateMatchesWithNotFound = (
+    matches: AnyRouteMatch[],
+    currentMatch: AnyRouteMatch,
+    err: NotFoundError,
+  ) => {
+    const matchesByRouteId = Object.fromEntries(
+      matches.map((match) => [match.routeId, match]),
+    ) as Record<string, AnyRouteMatch>
+
+    if (err.global) {
+      matchesByRouteId[rootRouteId]!.notFoundError = err
+    } else {
+      // If the err contains a routeId, start searching up from that route
+      let currentRoute = (this.routesById as any)[
+        err.route ?? currentMatch.routeId
+      ] as AnyRoute
+
+      // Go up the tree until we find a route with a notFoundComponent
+      while (!currentRoute.options.notFoundComponent) {
+        currentRoute = currentRoute?.parentRoute
+
+        invariant(
+          currentRoute,
+          'Found invalid route tree while trying to find not-found handler.',
+        )
+
+        if (currentRoute.id === rootRouteId) break
+      }
+
+      const match = matchesByRouteId[currentRoute.id]
+      invariant(match, 'Could not find match for route: ' + currentRoute.id)
+      match.notFoundError = err
+    }
+  }
+
+  hasNotFoundMatch = () => {
+    return this.__store.state.matches.some((d) => d.notFoundError)
+  }
+
   // resolveMatchPromise = (matchId: string, key: string, value: any) => {
   //   state.matches
   //     .find((d) => d.id === matchId)