@tanstack/router-core 1.166.7 → 1.167.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/router-core",
-  "version": "1.166.7",
+  "version": "1.167.1",
   "description": "Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -150,7 +150,7 @@
     "seroval-plugins": "^1.4.2",
     "tiny-invariant": "^1.3.3",
     "tiny-warning": "^1.0.3",
-    "@tanstack/history": "1.161.4"
+    "@tanstack/history": "1.161.5"
   },
   "devDependencies": {
     "esbuild": "^0.25.0",

package/src/index.ts

@@ -164,7 +164,9 @@ export type {
   FileBaseRouteOptions,
   BaseRouteOptions,
   UpdatableRouteOptions,
+  LoaderStaleReloadMode,
   RouteLoaderFn,
+  RouteLoaderEntry,
   LoaderFnContext,
   RouteContextFn,
   ContextOptions,

package/src/load-matches.ts

@@ -657,11 +657,13 @@ const runLoader = async (
       }
 
       // Kick off the loader!
-      const loaderResult = route.options.loader?.(
+      const routeLoader = route.options.loader
+      const loader =
+        typeof routeLoader === 'function' ? routeLoader : routeLoader?.handler
+      const loaderResult = loader?.(
         getLoaderContext(inner, matchPromises, matchId, index, route),
       )
-      const loaderResultIsPromise =
-        route.options.loader && isPromise(loaderResult)
+      const loaderResultIsPromise = !!loader && isPromise(loaderResult)
 
       const willLoadSomething = !!(
         loaderResultIsPromise ||
@@ -680,7 +682,7 @@ const runLoader = async (
         }))
       }
 
-      if (route.options.loader) {
+      if (loader) {
         const loaderData = loaderResultIsPromise
           ? await loaderResult
           : loaderResult
@@ -820,7 +822,11 @@ const loadRouteMatch = async (
       (invalid || (shouldReload ?? staleMatchShouldReload))
     if (preload && route.options.preload === false) {
       // Do nothing
-    } else if (loaderShouldRunAsync && !inner.sync) {
+    } else if (
+      loaderShouldRunAsync &&
+      !inner.sync &&
+      shouldReloadInBackground
+    ) {
       loaderIsRunningAsync = true
       ;(async () => {
         try {
@@ -835,7 +841,7 @@ const loadRouteMatch = async (
           }
         }
       })()
-    } else if (status !== 'success' || (loaderShouldRunAsync && inner.sync)) {
+    } else if (status !== 'success' || loaderShouldRunAsync) {
       await runLoader(inner, matchPromises, matchId, index, route)
     } else {
       syncMatchContext(inner, matchId, index)
@@ -846,6 +852,12 @@ const loadRouteMatch = async (
   let loaderShouldRunAsync = false
   let loaderIsRunningAsync = false
   const route = inner.router.looseRoutesById[routeId]!
+  const routeLoader = route.options.loader
+  const shouldReloadInBackground =
+    ((typeof routeLoader === 'function'
+      ? undefined
+      : routeLoader?.staleReloadMode) ??
+      inner.router.options.defaultStaleReloadMode) !== 'blocking'
 
   if (shouldSkipLoader(inner, matchId)) {
     const match = inner.router.getMatch(matchId)
@@ -871,7 +883,12 @@ const loadRouteMatch = async (
       // 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
-      if (prevMatch.status === 'success' && !inner.sync && !prevMatch.preload) {
+      if (
+        prevMatch.status === 'success' &&
+        !inner.sync &&
+        !prevMatch.preload &&
+        shouldReloadInBackground
+      ) {
         return prevMatch
       }
       await prevMatch._nonReactive.loaderPromise

package/src/route.ts

@@ -292,11 +292,44 @@ export type ResolveRouteContext<TRouteContextFn, TBeforeLoadFn> = Assign<
   ContextAsyncReturnType<TBeforeLoadFn>
 >
 
+export type ResolveRouteLoaderFn<TLoaderFn> = TLoaderFn extends {
+  handler: infer THandler
+}
+  ? THandler
+  : TLoaderFn
+
+export type RouteLoaderObject<
+  TRegister,
+  TParentRoute extends AnyRoute = AnyRoute,
+  TId extends string = string,
+  TParams = {},
+  TLoaderDeps = {},
+  TRouterContext = {},
+  TRouteContextFn = AnyContext,
+  TBeforeLoadFn = AnyContext,
+  TServerMiddlewares = unknown,
+  THandlers = undefined,
+> = {
+  handler: RouteLoaderFn<
+    TRegister,
+    TParentRoute,
+    TId,
+    TParams,
+    TLoaderDeps,
+    TRouterContext,
+    TRouteContextFn,
+    TBeforeLoadFn,
+    TServerMiddlewares,
+    THandlers
+  >
+  staleReloadMode?: LoaderStaleReloadMode
+}
+
 export type ResolveLoaderData<TLoaderFn> = unknown extends TLoaderFn
   ? TLoaderFn
-  : LooseAsyncReturnType<TLoaderFn> extends never
+  : LooseAsyncReturnType<ResolveRouteLoaderFn<TLoaderFn>> extends never
     ? undefined
-    : LooseAsyncReturnType<TLoaderFn>
+    : LooseAsyncReturnType<ResolveRouteLoaderFn<TLoaderFn>>
 
 export type ResolveFullSearchSchema<
   TParentRoute extends AnyRoute,
@@ -1010,8 +1043,7 @@ export interface FilebaseRouteOptionsInterface<
 
   loader?: Constrain<
     TLoaderFn,
-    (
-      ctx: LoaderFnContext<
+    | RouteLoaderFn<
         TRegister,
         TParentRoute,
         TId,
@@ -1022,13 +1054,19 @@ export interface FilebaseRouteOptionsInterface<
         TBeforeLoadFn,
         TServerMiddlewares,
         THandlers
-      >,
-    ) => ValidateSerializableLifecycleResult<
-      TRegister,
-      TParentRoute,
-      TSSR,
-      TLoaderFn
-    >
+      >
+    | RouteLoaderObject<
+        TRegister,
+        TParentRoute,
+        TId,
+        TParams,
+        TLoaderDeps,
+        TRouterContext,
+        TRouteContextFn,
+        TBeforeLoadFn,
+        TServerMiddlewares,
+        THandlers
+      >
   >
 }
 
@@ -1415,6 +1453,45 @@ export type RouteLoaderFn<
   >,
 ) => any
 
+export type LoaderStaleReloadMode = 'background' | 'blocking'
+
+export type RouteLoaderEntry<
+  TRegister,
+  TParentRoute extends AnyRoute = AnyRoute,
+  TId extends string = string,
+  TParams = {},
+  TLoaderDeps = {},
+  TRouterContext = {},
+  TRouteContextFn = AnyContext,
+  TBeforeLoadFn = AnyContext,
+  TServerMiddlewares = unknown,
+  THandlers = undefined,
+> =
+  | RouteLoaderFn<
+      TRegister,
+      TParentRoute,
+      TId,
+      TParams,
+      TLoaderDeps,
+      TRouterContext,
+      TRouteContextFn,
+      TBeforeLoadFn,
+      TServerMiddlewares,
+      THandlers
+    >
+  | RouteLoaderObject<
+      TRegister,
+      TParentRoute,
+      TId,
+      TParams,
+      TLoaderDeps,
+      TRouterContext,
+      TRouteContextFn,
+      TBeforeLoadFn,
+      TServerMiddlewares,
+      THandlers
+    >
+
 export interface LoaderFnContext<
   in out TRegister = unknown,
   in out TParentRoute extends AnyRoute = AnyRoute,

package/src/router.ts

@@ -72,6 +72,7 @@ import type {
   AnyContext,
   AnyRoute,
   AnyRouteWithContext,
+  LoaderStaleReloadMode,
   MakeRemountDepsOptionsUnion,
   RouteContextOptions,
   RouteLike,
@@ -238,6 +239,15 @@ export interface RouterOptions<
    * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#key-options)
    */
   defaultStaleTime?: number
+  /**
+   * The default stale reload mode a route loader should use if no `loader.staleReloadMode` is provided.
+   *
+   * `'background'` preserves the current stale-while-revalidate behavior.
+   * `'blocking'` waits for stale loader reloads to complete before resolving navigation.
+   *
+   * @default 'background'
+   */
+  defaultStaleReloadMode?: LoaderStaleReloadMode
   /**
    * The default `preloadStaleTime` a route should use if no preloadStaleTime is provided.
    *
@@ -790,6 +800,8 @@ export interface ServerSsr {
   isDehydrated: () => boolean
   isSerializationFinished: () => boolean
   onRenderFinished: (listener: () => void) => void
+  setRenderFinished: () => void
+  cleanup: () => void
   onSerializationFinished: (listener: () => void) => void
   dehydrate: () => Promise<void>
   takeBufferedScripts: () => RouterManagedTag | undefined