You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 45c4ad8
Browse filesBrowse the repository at this point in the historyBrowse files
Rewrite match loading around a lane-based scheduler that tracks each navigation, preload, and background reload as an ordered unit of work. This fixes pending/redirect/retry state leaking between overlapping navigations, restores correct SSR status codes for redirects, errors, and not-found responses, and closes hydration gaps where the client re-ran work the server had already completed.
9
+
10
+
- Invalidation now retires matching active preloads so older speculative loader results cannot become fresh cache data after invalidation.
11
+
- Route `headers()` now only runs on the server, matching the documented behavior — it is no longer invoked during client-side asset projection.
12
+
- Default `gcTime` and `preloadGcTime` are reduced from 30 minutes (`1_800_000`) to 5 minutes (`300_000`).
13
+
14
+
**Removed / changed public API**
15
+
16
+
-`RouterState` no longer includes `loadedAt`, `isTransitioning`, `statusCode`, or `redirect`. Use `match.updatedAt` in place of `loadedAt`; subscribe to `router.state.status` / `router.state.isLoading` in place of `isTransitioning`; server response status and redirect handling are now internal to the server loader and are no longer exposed on `router.state`.
17
+
-`RouteMatch.fetchCount` has been removed, with no replacement — it was purely informational.
18
+
-`RouteMatch.status` no longer includes `'redirected'` (it remains `'pending' | 'success' | 'error' | 'notFound'`) — redirected matches are dropped from the match list instead of being rendered.
19
+
-`RouteMatch.globalNotFound` has been renamed and privatized to the internal `_notFound` field. Use `match.status === 'notFound'` instead.
20
+
- Removed `RouterCore` members `getMatch()`, `updateMatch()`, `cancelMatch()`, and `cancelMatches()` — read matches from `router.state.matches` (e.g. `router.state.matches.find((m) => m.id === id)`); there is no replacement for mutating or cancelling an individual in-flight match from outside the router.
21
+
- Removed `hasNotFoundMatch()` — use `router.state.matches.some((m) => m.status === 'notFound')`.
22
+
- Removed `looseRoutesById` — use `routesById`.
23
+
- Removed `isPrerendering()`, `isViewTransitionTypesSupported`, and `viewTransitionPromise`, with no replacement.
24
+
- Removed `getParsedLocationHref()` and `clearExpiredCache()`, with no replacement — expired cache entries are now reconciled automatically as part of match commit.
25
+
- Removed `latestLoadPromise` and `beforeLoad()`, with no replacement.
26
+
-`commitLocationPromise` and `pendingBuiltLocation` are now private (`_commitPromise`, `_pendingLocation`) and no longer part of the public `RouterCore` surface.
27
+
- Removed the exported `GetMatchFn` and `UpdateMatchFn` types, along with the methods they typed.
28
+
- Removed the standalone `getMatchedRoutes()` export from `@tanstack/router-core` — use the `router.getMatchedRoutes()` instance method instead.
29
+
-`MatchRoutesOpts.preload` and `MatchRoutesOpts.dest` have been removed.
30
+
-`StartTransitionFn` is now `(fn, expected, urgent?) => Promise<boolean>` (previously `(fn) => void`). This only affects custom framework adapters that implement `startTransition`.
- A function that will be called when this route is matched and passed the raw search params from the current location and return valid parsed search params. If this function throws, the route will be put into an error state and the error will be thrown during render. If this function does not throw, its return value will be used as the route's search params and the return type will be inferred into the rest of the router.
59
+
- This is a planning callback. It must be deterministic and side-effect-free for the same input; do not navigate or mutate application/router state from it.
59
60
- Optionally, the parameter type can be tagged with the `SearchSchemaInput` type like this: `(searchParams: TSearchSchemaInput & SearchSchemaInput) => TSearchSchema`. If this tag is present, `TSearchSchemaInput` will be used to type the `search` property of `<Link />` and `navigate()`**instead of**`TSearchSchema`. The difference between `TSearchSchemaInput` and `TSearchSchema` can be useful, for example, to express optional search parameters.
60
61
61
62
### `search.middlewares` property
@@ -70,6 +71,7 @@ The `RouteOptions` type accepts an object with the following properties:
- A function that will be called when this route is matched and passed the raw params from the current location and return valid parsed params. If this function throws, the route will be put into an error state and the error will be thrown during render. If this function does not throw, its return value will be used as the route's params and the return type will be inferred into the rest of the router.
74
+
- This is a planning callback. It must be deterministic and side-effect-free for the same input.
73
75
74
76
### `stringifyParams` method (⚠️ deprecated, use `params.stringify` instead)
75
77
@@ -82,6 +84,7 @@ The `RouteOptions` type accepts an object with the following properties:
- A function that will be called when this route is matched and passed the raw params from the current location and return valid parsed params. If this function throws, the route will be put into an error state and the error will be thrown during render. If this function returns parsed params, its return value will be used as the route's params and the return type will be inferred into the rest of the router.
87
+
- This is a planning callback. It must be deterministic and side-effect-free for the same input.
85
88
- Experimental: returning `false` during incoming route matching skips this route and allows matching to continue to another candidate route.
- A function that will be called before this route is matched to provide additional unique identification to the route match and serve as a dependency tracker for when the match should be reloaded. It should return any serializable value that can uniquely identify the route match from navigation to navigation.
182
+
- This is a planning callback and cache-key function. It must be deterministic and side-effect-free for the same validated search input. The returned value and any serialization methods on it, such as `toJSON`, must also be side-effect-free.
179
183
- By default, path params are already used to uniquely identify a route match, so it's unnecessary to return these here.
180
184
- If your route match relies on search params for unique identification, it's required that you return them here so they can be made available in the `loader`'s `deps` argument.
- Defaults to `routerOptions.defaultPreloadStaleTime`, which defaults to `30_000` ms (30 seconds)
194
-
- The amount of time in milliseconds that a route match's loader data will be considered fresh when preloading. If a route match is preloaded again within this time frame, its loader data will not be reloaded. If a route match is loaded (for navigation) within this time frame, the normal `staleTime` is used instead.
198
+
- The amount of time in milliseconds that loader data produced by a preload is considered fresh. Another preload or the first navigation can reuse it within this interval. After navigation accepts the generation, subsequent freshness uses `staleTime`.
195
199
196
200
### `gcTime` property
197
201
198
202
- Type: `number`
199
203
- Optional
200
-
- Defaults to `routerOptions.defaultGcTime`, which defaults to 30 minutes.
201
-
- The amount of time in milliseconds that a route match's loader data will be kept in memory after a preload or it is no longer in use.
204
+
- Defaults to `routerOptions.defaultGcTime`, which defaults to 5 minutes.
205
+
- The amount of time in milliseconds that loader data from an ordinary load will be kept in memory after it is no longer in use.
- Defaults to `routerOptions.defaultPendingMinMs` which defaults to `500`
235
239
- The minimum amount of time in milliseconds that the pending component will be shown for if it is shown. This is useful to prevent the pending component from flashing on the screen for a split second.
236
240
237
-
### `preloadMaxAge` property
241
+
### `preloadGcTime` property
238
242
239
243
- Type: `number`
240
244
- Optional
241
-
- Defaults to `30_000` ms (30 seconds)
242
-
- The maximum amount of time in milliseconds that a route's preloaded route data will be cached for. If a route is not matched within this time frame, its loader data will be discarded.
245
+
- Defaults to `routerOptions.defaultPreloadGcTime`, which defaults to 5 minutes.
246
+
- The amount of time in milliseconds that loader data produced by a preload can remain in memory while it is not in use. This controls retention; use `preloadStaleTime` to control whether retained data is fresh enough to reuse without reloading.
243
247
244
248
### `preSearchFilters` property (⚠️ deprecated, use `search.middlewares` instead)
Copy file name to clipboardExpand all lines: docs/router/api/router/RouterStateType.md
+16-13Lines changed: 16 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,16 +3,17 @@ id: RouterStateType
3
3
title: RouterState type
4
4
---
5
5
6
-
The `RouterState` type represents shape of the internal state of the router. The Router's internal state is useful, if you need to access certain internals of the router, such as any pending matches, is the router in its loading state, etc.
6
+
The `RouterState` type represents the observable state of the router, including
7
+
the requested and resolved locations, match presentation, and foreground loading
8
+
status.
7
9
8
10
```tsx
9
11
typeRouterState= {
10
12
status:'pending'|'idle'
11
13
isLoading:boolean
12
-
isTransitioning:boolean
13
14
matches:Array<RouteMatch>
14
15
location:ParsedLocation
15
-
resolvedLocation:ParsedLocation
16
+
resolvedLocation?:ParsedLocation
16
17
}
17
18
```
18
19
@@ -23,22 +24,24 @@ The `RouterState` type contains all of the properties that are available on the
23
24
### `status` property
24
25
25
26
- Type: `'pending'|'idle'`
26
-
- The current status of the router. If the router is pending, it means that it is currently loading a route or the router is still transitioning to the new route.
27
+
- The current foreground status of the router. `pending`means the requested route is still loading or waiting for its framework transition to settle.
27
28
28
29
### `isLoading` property
29
30
30
31
- Type: `boolean`
31
-
- `true` if the router is currently loading a route or waiting for a route to finish loading.
32
-
33
-
### `isTransitioning` property
34
-
35
-
- Type: `boolean`
36
-
- `true` if the router is currently transitioning to a new route.
32
+
- `true` when `status` is `pending`.
33
+
- Background loader refreshes do not change this value. Inspect each match's `isFetching` field to observe foreground `beforeLoad`/loader work and background loader work.
0 commit comments