@depup/tanstack__react-router 1.166.8-depup.0 → 1.167.0-depup.0

package/dist/llms/rules/guide.js

@@ -1904,7 +1904,7 @@ The router cache is built-in and is as easy as returning data from any route's \
 
 ## Route \`loader\`s
 
-Route \`loader\` functions are called when a route match is loaded. They are called with a single parameter which is an object containing many helpful properties. We'll go over those in a bit, but first, let's look at an example of a route \`loader\` function:
+Route \`loader\` functions are called when a route match is loaded. They are called with a single parameter which is an object containing many helpful properties. We'll go over those in a bit, but first, let's look at the two supported \`loader\` forms:
 
 \`\`\`tsx
 // src/routes/posts.tsx
@@ -1913,6 +1913,17 @@ export const Route = createFileRoute('/posts')({
 })
 \`\`\`
 
+\`\`\`tsx
+// src/routes/posts.tsx
+export const Route = createFileRoute('/posts')({
+  loader: {
+    handler: () => fetchPosts(),
+  },
+})
+\`\`\`
+
+Use the object form when you want to configure loader-specific behavior such as \`staleReloadMode\`.
+
 ## \`loader\` Parameters
 
 The \`loader\` function receives a single object with the following properties:
@@ -1998,12 +2009,16 @@ To control router dependencies and "freshness", TanStack Router provides a pleth
   - The number of milliseconds that a route's data should be kept in the cache before being garbage collected.
 - \`routeOptions.shouldReload\`
   - A function that receives the same \`beforeLoad\` and \`loaderContext\` parameters and returns a boolean indicating if the route should reload. This offers one more level of control over when a route should reload beyond \`staleTime\` and \`loaderDeps\` and can be used to implement patterns similar to Remix's \`shouldLoad\` option.
+- \`routeOptions.loader.staleReloadMode\`
+- \`routerOptions.defaultStaleReloadMode\`
+  - Controls what happens when a matched route already has stale successful data. Use \`'background'\` for stale-while-revalidate, or \`'blocking'\` to wait for the stale loader reload to finish before continuing.
 
 ### ⚠️ Some Important Defaults
 
 - By default, the \`staleTime\` is set to \`0\`, meaning that the route's data is immediately considered stale. Stale matches are reloaded in the background when the route is entered again, when its loader key changes (path params used by the route or \`loaderDeps\`), or when \`router.load()\` is called explicitly.
 - By default, a previously preloaded route is considered fresh for **30 seconds**. This means if a route is preloaded, then preloaded again within 30 seconds, the second preload will be ignored. This prevents unnecessary preloads from happening too frequently. **When a route is loaded normally, the standard \`staleTime\` is used.**
 - By default, the \`gcTime\` is set to **30 minutes**, meaning that any route data that has not been accessed in 30 minutes will be garbage collected and removed from the cache.
+- By default, \`staleReloadMode\` is \`'background'\`, so stale successful matches keep rendering with their existing \`loaderData\` while the loader revalidates in the background.
 - \`router.invalidate()\` will force all active routes to reload their loaders immediately and mark every cached route's data as stale.
 
 ### Using \`loaderDeps\` to access search params
@@ -2063,9 +2078,36 @@ export const Route = createFileRoute('/posts')({
 
 By passing \`10_000\` to the \`staleTime\` option, we are telling the router to consider the route's data fresh for 10 seconds. This means that if the user navigates to \`/posts\` from \`/about\` within 10 seconds of the last loader result, the route's data will not be reloaded. If the user then navigates to \`/posts\` from \`/about\` after 10 seconds, the route's data will be reloaded **in the background**.
 
-## Turning off stale-while-revalidate caching
+## Choosing background vs blocking stale reloads
+
+By default, stale successful matches use stale-while-revalidate behavior. That means the router can render with the existing \`loaderData\` immediately and then refresh it in the background.
+
+If you want a specific loader to wait for a stale reload to finish before continuing, use the object form and set \`staleReloadMode: 'blocking'\`:
+
+\`\`\`tsx
+// /routes/posts.tsx
+export const Route = createFileRoute('/posts')({
+  loader: {
+    handler: () => fetchPosts(),
+    staleReloadMode: 'blocking',
+  },
+})
+\`\`\`
+
+You can also change the default for the entire router:
+
+\`\`\`tsx
+const router = createRouter({
+  routeTree,
+  defaultStaleReloadMode: 'blocking',
+})
+\`\`\`
+
+Use \`'background'\` when showing stale data during revalidation is acceptable. Use \`'blocking'\` when you want stale matches to behave more like a fresh load and wait for the new loader result.
 
-To disable stale-while-revalidate caching for a route, set the \`staleTime\` option to \`Infinity\`:
+## Turning off automatic stale reloads
+
+To disable automatic stale reloads for a route, set the \`staleTime\` option to \`Infinity\`:
 
 \`\`\`tsx
 // /routes/posts.tsx
@@ -2084,6 +2126,11 @@ const router = createRouter({
 })
 \`\`\`
 
+This differs from \`staleReloadMode: 'blocking'\`:
+
+- \`staleTime: Infinity\` prevents the route from becoming stale in the first place
+- \`staleReloadMode: 'blocking'\` still allows stale reloads, but waits for them instead of doing them in the background
+
 ## Using \`shouldReload\` and \`gcTime\` to opt-out of caching
 
 Similar to Remix's default functionality, you may want to configure a route to only load on entry or when critical loader deps change. You can do this by using the \`gcTime\` option combined with the \`shouldReload\` option, which accepts either a \`boolean\` or a function that receives the same \`beforeLoad\` and \`loaderContext\` parameters and returns a boolean indicating if the route should reload.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@depup/tanstack__react-router",
-  "version": "1.166.8-depup.0",
+  "version": "1.167.0-depup.0",
   "description": "[DepUp] Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -86,7 +86,7 @@
     "tiny-invariant": "^1.3.3",
     "tiny-warning": "^1.0.3",
     "@tanstack/history": "1.161.4",
-    "@tanstack/router-core": "1.166.7"
+    "@tanstack/router-core": "1.167.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",
@@ -135,8 +135,8 @@
     },
     "depsUpdated": 2,
     "originalPackage": "@tanstack/react-router",
-    "originalVersion": "1.166.8",
-    "processedAt": "2026-03-14T00:32:41.859Z",
+    "originalVersion": "1.167.0",
+    "processedAt": "2026-03-14T08:12:03.548Z",
     "smokeTest": "passed"
   }
 }

package/src/fileRoute.ts

@@ -28,7 +28,7 @@ import type {
   RouteById,
   RouteConstraints,
   RouteIds,
-  RouteLoaderFn,
+  RouteLoaderEntry,
   UpdatableRouteOptions,
   UseNavigateResult,
 } from '@tanstack/router-core'
@@ -174,7 +174,7 @@ export function FileRouteLoader<
 ): <TLoaderFn>(
   loaderFn: Constrain<
     TLoaderFn,
-    RouteLoaderFn<
+    RouteLoaderEntry<
       Register,
       TRoute['parentRoute'],
       TRoute['types']['id'],