@tanstack/react-router 1.6.0 → 1.7.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/react-router",
   "author": "Tanner Linsley",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "license": "MIT",
   "repository": "tanstack/router",
   "homepage": "https://tanstack.com/router",
@@ -44,7 +44,7 @@
     "@tanstack/store": "^0.1.3",
     "tiny-invariant": "^1.3.1",
     "tiny-warning": "^1.0.3",
-    "@tanstack/history": "1.6.0"
+    "@tanstack/history": "1.7.0"
   },
   "scripts": {
     "build": "rollup --config rollup.config.js"

package/src/Matches.tsx

@@ -162,7 +162,13 @@ function MatchInner({
   })
 
   if (match.status === 'error') {
-    throw match.error
+    if (isServerSideError(match.error)) {
+      const deserializeError =
+        router.options.errorSerializer?.deserialize ?? defaultDeserializeError
+      throw deserializeError(match.error.data)
+    } else {
+      throw match.error
+    }
   }
 
   if (match.status === 'pending') {
@@ -423,3 +429,24 @@ export function useLoaderData<
     },
   })
 }
+
+export function isServerSideError(error: unknown): error is {
+  __isServerError: true
+  data: Record<string, any>
+} {
+  if (!(typeof error === 'object' && error && 'data' in error)) return false
+  if (!('__isServerError' in error && error.__isServerError)) return false
+  if (!(typeof error.data === 'object' && error.data)) return false
+
+  return error.__isServerError === true
+}
+
+export function defaultDeserializeError(serializedData: Record<string, any>) {
+  if ('name' in serializedData && 'message' in serializedData) {
+    const error = new Error(serializedData.message)
+    error.name = serializedData.name
+    return error
+  }
+
+  return serializedData.data
+}

package/src/awaited.tsx

@@ -1,5 +1,8 @@
+import warning from 'tiny-warning'
+import { defaultDeserializeError, isServerSideError } from './Matches'
 import { useRouter } from './useRouter'
 import { DeferredPromise, isDehydratedDeferred } from './defer'
+import { defaultSerializeError } from './router'
 
 export type AwaitOptions<T> = {
   promise: DeferredPromise<T>
@@ -13,6 +16,7 @@ export function useAwaited<T>({ promise }: AwaitOptions<T>): [T] {
 
   if (isDehydratedDeferred(promise)) {
     state = router.hydrateData(key)!
+    if (!state) throw new Error('Could not find dehydrated data')
     promise = Promise.resolve(state.data) as DeferredPromise<any>
     promise.__deferredState = state
   }
@@ -22,7 +26,27 @@ export function useAwaited<T>({ promise }: AwaitOptions<T>): [T] {
   }
 
   if (state.status === 'error') {
-    throw state.error
+    if (typeof document !== 'undefined') {
+      if (isServerSideError(state.error)) {
+        throw (
+          router.options.errorSerializer?.deserialize ?? defaultDeserializeError
+        )(state.error.data as any)
+      } else {
+        warning(
+          false,
+          "Encountered a server-side error that doesn't fit the expected shape",
+        )
+        throw state.error
+      }
+    } else {
+      router.dehydrateData(key, state)
+      throw {
+        data: (
+          router.options.errorSerializer?.serialize ?? defaultSerializeError
+        )(state.error),
+        __isServerError: true,
+      }
+    }
   }
 
   router.dehydrateData(key, state)

package/src/defer.ts

@@ -1,3 +1,5 @@
+import { defaultSerializeError } from './router'
+
 export type DeferredPromiseState<T> = { uid: string } & (
   | {
       status: 'pending'
@@ -19,7 +21,12 @@ export type DeferredPromise<T> = Promise<T> & {
   __deferredState: DeferredPromiseState<T>
 }
 
-export function defer<T>(_promise: Promise<T>) {
+export function defer<T>(
+  _promise: Promise<T>,
+  options?: {
+    serializeError?: typeof defaultSerializeError
+  },
+) {
   const promise = _promise as DeferredPromise<T>
 
   if (!promise.__deferredState) {
@@ -37,7 +44,10 @@ export function defer<T>(_promise: Promise<T>) {
       })
       .catch((error) => {
         state.status = 'error' as any
-        state.error = error
+        state.error = {
+          data: (options?.serializeError ?? defaultSerializeError)(error),
+          __isServerError: true,
+        }
       })
   }
 

package/src/router.ts

@@ -105,6 +105,7 @@ export type RouterContextOptions<TRouteTree extends AnyRoute> =
 export interface RouterOptions<
   TRouteTree extends AnyRoute,
   TDehydrated extends Record<string, any> = Record<string, any>,
+  TSerializedError extends Record<string, any> = Record<string, any>,
 > {
   history?: RouterHistory
   stringifySearch?: SearchSerializer
@@ -131,6 +132,11 @@ export interface RouterOptions<
   Wrap?: (props: { children: any }) => JSX.Element
   InnerWrap?: (props: { children: any }) => JSX.Element
   notFoundRoute?: AnyRoute
+  errorSerializer?: RouterErrorSerializer<TSerializedError>
+}
+export interface RouterErrorSerializer<TSerializedError> {
+  serialize: (err: unknown) => TSerializedError
+  deserialize: (err: TSerializedError) => unknown
 }
 
 export interface RouterState<TRouteTree extends AnyRoute = AnyRoute> {
@@ -180,7 +186,8 @@ export interface DehydratedRouter {
 export type RouterConstructorOptions<
   TRouteTree extends AnyRoute,
   TDehydrated extends Record<string, any>,
-> = Omit<RouterOptions<TRouteTree, TDehydrated>, 'context'> &
+  TSerializedError extends Record<string, any>,
+> = Omit<RouterOptions<TRouteTree, TDehydrated, TSerializedError>, 'context'> &
   RouterContextOptions<TRouteTree>
 
 export const componentTypes = [
@@ -220,6 +227,7 @@ export type RouterListener<TRouterEvent extends RouterEvent> = {
 export class Router<
   TRouteTree extends AnyRoute = AnyRoute,
   TDehydrated extends Record<string, any> = Record<string, any>,
+  TSerializedError extends Record<string, any> = Record<string, any>,
 > {
   // Option-independent properties
   tempLocationKey: string | undefined = `${Math.round(
@@ -235,7 +243,7 @@ export class Router<
   // Must build in constructor
   __store!: Store<RouterState<TRouteTree>>
   options!: PickAsRequired<
-    RouterOptions<TRouteTree, TDehydrated>,
+    RouterOptions<TRouteTree, TDehydrated, TSerializedError>,
     'stringifySearch' | 'parseSearch' | 'context'
   >
   history!: RouterHistory
@@ -246,7 +254,13 @@ export class Router<
   routesByPath!: RoutesByPath<TRouteTree>
   flatRoutes!: AnyRoute[]
 
-  constructor(options: RouterConstructorOptions<TRouteTree, TDehydrated>) {
+  constructor(
+    options: RouterConstructorOptions<
+      TRouteTree,
+      TDehydrated,
+      TSerializedError
+    >,
+  ) {
     this.update({
       defaultPreloadDelay: 50,
       defaultPendingMs: 1000,
@@ -263,7 +277,13 @@ export class Router<
   // router can be used in a non-react environment if necessary
   startReactTransition: (fn: () => void) => void = (fn) => fn()
 
-  update = (newOptions: RouterConstructorOptions<TRouteTree, TDehydrated>) => {
+  update = (
+    newOptions: RouterConstructorOptions<
+      TRouteTree,
+      TDehydrated,
+      TSerializedError
+    >,
+  ) => {
     const previousOptions = this.options
     this.options = {
       ...this.options,
@@ -1616,11 +1636,22 @@ export class Router<
   }
 
   dehydrate = (): DehydratedRouter => {
+    const pickError =
+      this.options.errorSerializer?.serialize ?? defaultSerializeError
+
     return {
       state: {
-        dehydratedMatches: this.state.matches.map((d) =>
-          pick(d, ['id', 'status', 'updatedAt', 'loaderData']),
-        ),
+        dehydratedMatches: this.state.matches.map((d) => ({
+          ...pick(d, ['id', 'status', 'updatedAt', 'loaderData']),
+          // If an error occurs server-side during SSRing,
+          // send a small subset of the error to the client
+          error: d.error
+            ? {
+                data: pickError(d.error),
+                __isServerError: true,
+              }
+            : undefined,
+        })),
       },
     }
   }
@@ -1713,3 +1744,15 @@ export function getInitialRouterState(
     lastUpdated: Date.now(),
   }
 }
+
+export function defaultSerializeError(err: unknown) {
+  if (err instanceof Error)
+    return {
+      name: err.name,
+      message: err.message,
+    }
+
+  return {
+    data: err,
+  }
+}