Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added jsdoc and docs for RouterOptions #3537

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Added jsdoc and docs for RouterOptions #3537

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/router/framework/react/guide/preloading.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,10 @@ export const Route = createFileRoute('/posts/$postId')({
})
```

## Preloaded data garbage collection & `preloadGcTime`

Similarly to `preloadStaleTime`, you can control how long preloaded data should be kept in the cache before being garbage collected by setting either `routerOptions.defaultPreloadGcTime` or `routeOptions.preloadGcTime`. **By default, preloaded data is kept in cache for 30 minutes.**.

## Preloading with External Libraries

When integrating external caching libraries like React Query, which have their own mechanisms for determining stale data, you may want to override the default preloading and stale-while-revalidate logic of TanStack Router. These libraries often use options like staleTime to control the freshness of data.
Expand Down
70 changes: 67 additions & 3 deletions packages/react-router/src/route.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -382,21 +382,85 @@ export interface UpdatableRouteOptions<
in out TRouteContextFn,
in out TBeforeLoadFn,
> extends UpdatableStaticRouteOption {
// If true, this route will be matched as case-sensitive
/**
* If true, this route will be matched as case-sensitive.
*/
caseSensitive?: boolean
// If true, this route will be forcefully wrapped in a suspense boundary
/**
* If true, this route will be forcefully wrapped in a suspense boundary.
*/
wrapInSuspense?: boolean
// The content to be rendered when the route is matched. If no component is provided, defaults to `<Outlet />`
/**
* The content to be rendered when the route is matched. If no component is provided, defaults to `<Outlet />`.
*/
component?: RouteComponent
/**
* The component that is rendered when an error occurs during the route loading or rendering lifecycle
* If not set, defaults to `defaultErrorComponent`.
*
* @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#handling-errors-with-routeoptionserrorcomponent)
*/
errorComponent?: false | null | ErrorRouteComponent
/**
* The `notFoundComponent` will be displayed when no route is matched.
* If not set, defaults to `defaultNotFoundComponent`.
*
* @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/not-found-errors#default-router-wide-not-found-handling)
*/
notFoundComponent?: NotFoundRouteComponent
/**
* The `pendingComponent` will be displayed for loaders which take longer than `pendingMs` to resolve.
* If not set, defaults to `defaultPendingComponent` (**unset by default**).
*
* @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#showing-a-pending-component)
*/
pendingComponent?: RouteComponent
/**
* The time (in milliseconds) to wait before showing the pending component.
* If not set, defaults to `defaultPendingMs`.
*
* @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#showing-a-pending-component)
*/
pendingMs?: number
/**
* The minimum time (in milliseconds) a pending component would be potentially displayed for. This avoids flashing the pending component for very short durations.
* If not set, defaults to `defaultPendingMs`.
*
* @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#avoiding-pending-component-flash)
*/
pendingMinMs?: number
/**
* The time (in milliseconds) for which a route's data should be considered fresh when attempting to load.
* If not set, defaults to `defaultStaleTime`.
*
* @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#key-options)
*/
staleTime?: number
/**
* The time (in milliseconds) for which a route's data should be kept in the cache before being garbage collected.
*
* @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#key-options)
*/
gcTime?: number
/**
* Turn on/off data preloading for this route.
*
* @todo allow specifying strategies available in `defaultPreload` ('intent' | 'viewport' | 'render')
* @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading#supported-preloading-strategies)
*/
preload?: boolean
/**
* The time (in milliseconds) for which a route's **preloaded data** should be considered fresh when attempting to load.
*
* @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading#built-in-preloading--preloadstaletime)
*/
preloadStaleTime?: number
/**
* The time (in milliseconds) for which a route's **preloaded data** should be kept in the cache before being garbage collected.
* If not set, defaults to `defaultPreloadGcTime`.
*
* @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading#built-in-preloading--preloadstaletime)
*/
preloadGcTime?: number
search?: {
middlewares?: Array<
Expand Down
14 changes: 8 additions & 6 deletions packages/react-router/src/router.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,9 +187,11 @@ export interface RouterOptions<
*
* If `'viewport'`, routes will be preloaded by default when they are within the viewport.
*
* If `'render'`, routes will be preloaded by default when the corresponding `Link` component gets rendered.
*
* @default false
* @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpreload-property)
* @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading)
* @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading#supported-preloading-strategies)
*/
defaultPreload?: false | 'intent' | 'viewport' | 'render'
/**
Expand Down Expand Up @@ -223,15 +225,15 @@ export interface RouterOptions<
*/
defaultPendingComponent?: RouteComponent
/**
* The default `pendingMs` a route should use if no pendingMs is provided.
* The default `pendingMs` a route should use if no `pendingMs` is provided.
*
* @default 1000
* @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpendingms-property)
* @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#avoiding-pending-component-flash)
* @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#showing-a-pending-component)
*/
defaultPendingMs?: number
/**
* The default `pendingMinMs` a route should use if no pendingMinMs is provided.
* The default `pendingMinMs` a route should use if no `pendingMinMs` is provided.
*
* @default 500
* @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpendingminms-property)
Expand All @@ -251,15 +253,15 @@ export interface RouterOptions<
*
* @default 30_000 `(30 seconds)`
* @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpreloadstaletime-property)
* @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading)
* @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading#built-in-preloading--preloadstaletime)
*/
defaultPreloadStaleTime?: number
/**
* The default `defaultPreloadGcTime` a route should use if no preloadGcTime is provided.
*
* @default 1_800_000 `(30 minutes)`
* @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpreloadgctime-property)
* @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading)
* @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading#built-in-preloading--preloadstaletime)
*/
defaultPreloadGcTime?: number
/**
Expand Down