import { Store } from '@tanstack/store'; import { SearchParser, SearchSerializer } from './searchParams.cjs'; import { AnyRedirect, ResolvedRedirect } from './redirect.cjs'; import { HistoryLocation, HistoryState, ParsedHistoryState, RouterHistory } from '@tanstack/history'; import { ControlledPromise, NoInfer, NonNullableUpdater, PickAsRequired, Updater } from './utils.cjs'; import { ParsedLocation } from './location.cjs'; import { DeferredPromiseState } from './defer.cjs'; import { AnyContext, AnyRoute, AnyRouteWithContext, MakeRemountDepsOptionsUnion, RouteMask } from './route.cjs'; import { FullSearchSchema, RouteById, RoutePaths, RoutesById, RoutesByPath } from './routeInfo.cjs'; import { AnyRouteMatch, MakeRouteMatch, MakeRouteMatchUnion, MatchRouteOptions } from './Matches.cjs'; import { BuildLocationFn, CommitLocationOptions, NavigateFn } from './RouterProvider.cjs'; import { Manifest } from './manifest.cjs'; import { StartSerializer } from './serializer.cjs'; import { AnySchema } from './validators.cjs'; import { NavigateOptions, ResolveRelativePath, ToOptions } from './link.cjs'; import { NotFoundError } from './not-found.cjs'; declare global { interface Window { __TSR_ROUTER__?: AnyRouter; } } export type ControllablePromise = Promise & { resolve: (value: T) => void; reject: (value?: any) => void; }; export type InjectedHtmlEntry = Promise; export interface Register { } export type RegisteredRouter = Register extends { router: infer TRouter extends AnyRouter; } ? TRouter : AnyRouter; export type DefaultRemountDepsFn = (opts: MakeRemountDepsOptionsUnion) => any; export interface DefaultRouterOptionsExtensions { } export interface RouterOptionsExtensions extends DefaultRouterOptionsExtensions { } export interface RouterOptions = Record> extends RouterOptionsExtensions { /** * The history object that will be used to manage the browser history. * * If not provided, a new createBrowserHistory instance will be created and used. * * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#history-property) * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/history-types) */ history?: TRouterHistory; /** * A function that will be used to stringify search params when generating links. * * @default defaultStringifySearch * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#stringifysearch-method) * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/custom-search-param-serialization) */ stringifySearch?: SearchSerializer; /** * A function that will be used to parse search params when parsing the current location. * * @default defaultParseSearch * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#parsesearch-method) * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/custom-search-param-serialization) */ parseSearch?: SearchParser; /** * If `false`, routes will not be preloaded by default in any way. * * If `'intent'`, routes will be preloaded by default when the user hovers over a link or a `touchstart` event is detected on a ``. * * If `'viewport'`, routes will be preloaded by default when they are within the viewport. * * @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) */ defaultPreload?: false | 'intent' | 'viewport' | 'render'; /** * The delay in milliseconds that a route must be hovered over or touched before it is preloaded. * * @default 50 * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultpreloaddelay-property) * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/preloading#preload-delay) */ defaultPreloadDelay?: number; /** * 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) */ defaultPendingMs?: number; /** * 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) * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#avoiding-pending-component-flash) */ defaultPendingMinMs?: number; /** * The default `staleTime` a route should use if no staleTime is provided. This is the time in milliseconds that a route will be considered fresh. * * @default 0 * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultstaletime-property) * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#key-options) */ defaultStaleTime?: number; /** * The default `preloadStaleTime` a route should use if no preloadStaleTime is provided. * * @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) */ 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) */ defaultPreloadGcTime?: number; /** * If `true`, route navigations will called using `document.startViewTransition()`. * * If the browser does not support this api, this option will be ignored. * * See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document/startViewTransition) for more information on how this function works. * * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultviewtransition-property) */ defaultViewTransition?: boolean | ViewTransitionOptions; /** * The default `hashScrollIntoView` a route should use if no hashScrollIntoView is provided while navigating * * See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView) for more information on `ScrollIntoViewOptions`. * * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaulthashscrollintoview-property) */ defaultHashScrollIntoView?: boolean | ScrollIntoViewOptions; /** * @default 'fuzzy' * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#notfoundmode-property) * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/not-found-errors#the-notfoundmode-option) */ notFoundMode?: 'root' | 'fuzzy'; /** * The default `gcTime` a route should use if no gcTime is provided. * * @default 1_800_000 `(30 minutes)` * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultgctime-property) * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/data-loading#key-options) */ defaultGcTime?: number; /** * If `true`, all routes will be matched as case-sensitive. * * @default false * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#casesensitive-property) */ caseSensitive?: boolean; /** * * The route tree that will be used to configure the router instance. * * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#routetree-property) * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/routing/route-trees) */ routeTree?: TRouteTree; /** * The basepath for then entire router. This is useful for mounting a router instance at a subpath. * * @default '/' * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#basepath-property) */ basepath?: string; /** * The root context that will be provided to all routes in the route tree. * * This can be used to provide a context to all routes in the tree without having to provide it to each route individually. * * Optional or required if the root route was created with [`createRootRouteWithContext()`](https://tanstack.com/router/latest/docs/framework/react/api/router/createRootRouteWithContextFunction). * * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#context-property) * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/router-context) */ context?: InferRouterContext; /** * A function that will be called when the router is dehydrated. * * The return value of this function will be serialized and stored in the router's dehydrated state. * * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#dehydrate-method) * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/external-data-loading#critical-dehydrationhydration) */ dehydrate?: () => TDehydrated; /** * A function that will be called when the router is hydrated. * * The return value of this function will be serialized and stored in the router's dehydrated state. * * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#hydrate-method) * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/external-data-loading#critical-dehydrationhydration) */ hydrate?: (dehydrated: TDehydrated) => void; /** * An array of route masks that will be used to mask routes in the route tree. * * Route masking is when you display a route at a different path than the one it is configured to match, like a modal popup that when shared will unmask to the modal's content instead of the modal's context. * * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#routemasks-property) * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/route-masking) */ routeMasks?: Array>; /** * If `true`, route masks will, by default, be removed when the page is reloaded. * * This can be overridden on a per-mask basis by setting the `unmaskOnReload` option on the mask, or on a per-navigation basis by setting the `unmaskOnReload` option in the `Navigate` options. * * @default false * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#unmaskonreload-property) * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/route-masking#unmasking-on-page-reload) */ unmaskOnReload?: boolean; /** * Use `notFoundComponent` instead. * * @deprecated * See https://tanstack.com/router/v1/docs/guide/not-found-errors#migrating-from-notfoundroute for more info. * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#notfoundroute-property) */ notFoundRoute?: AnyRoute; /** * Configures how trailing slashes are treated. * * - `'always'` will add a trailing slash if not present * - `'never'` will remove the trailing slash if present * - `'preserve'` will not modify the trailing slash. * * @default 'never' * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#trailingslash-property) */ trailingSlash?: TTrailingSlashOption; /** * While usually automatic, sometimes it can be useful to force the router into a server-side state, e.g. when using the router in a non-browser environment that has access to a global.document object. * * @default typeof document !== 'undefined' * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#isserver-property) */ isServer?: boolean; defaultSsr?: boolean; search?: { /** * Configures how unknown search params (= not returned by any `validateSearch`) are treated. * * @default false * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#search.strict-property) */ strict?: boolean; }; /** * Configures whether structural sharing is enabled by default for fine-grained selectors. * * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultstructuralsharing-property) */ defaultStructuralSharing?: TDefaultStructuralSharingOption; /** * Configures which URI characters are allowed in path params that would ordinarily be escaped by encodeURIComponent. * * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#pathparamsallowedcharacters-property) * @link [Guide](https://tanstack.com/router/latest/docs/framework/react/guide/path-params#allowed-characters) */ pathParamsAllowedCharacters?: Array<';' | ':' | '@' | '&' | '=' | '+' | '$' | ','>; defaultRemountDeps?: DefaultRemountDepsFn; /** * If `true`, scroll restoration will be enabled * * @default false */ scrollRestoration?: boolean; /** * A function that will be called to get the key for the scroll restoration cache. * * @default (location) => location.href */ getScrollRestorationKey?: (location: ParsedLocation) => string; /** * The default behavior for scroll restoration. * * @default 'auto' */ scrollRestorationBehavior?: ScrollBehavior; /** * An array of selectors that will be used to scroll to the top of the page in addition to `window` * * @default ['window'] */ scrollToTopSelectors?: Array; } export interface RouterState { status: 'pending' | 'idle'; loadedAt: number; isLoading: boolean; isTransitioning: boolean; matches: Array; pendingMatches?: Array; cachedMatches: Array; location: ParsedLocation>; resolvedLocation?: ParsedLocation>; statusCode: number; redirect?: ResolvedRedirect; } export interface BuildNextOptions { to?: string | number | null; params?: true | Updater; search?: true | Updater; hash?: true | Updater; state?: true | NonNullableUpdater; mask?: { to?: string | number | null; params?: true | Updater; search?: true | Updater; hash?: true | Updater; state?: true | NonNullableUpdater; unmaskOnReload?: boolean; }; from?: string; _fromLocation?: ParsedLocation; href?: string; } type NavigationEventInfo = { fromLocation?: ParsedLocation; toLocation: ParsedLocation; pathChanged: boolean; hrefChanged: boolean; hashChanged: boolean; }; export type RouterEvents = { onBeforeNavigate: { type: 'onBeforeNavigate'; } & NavigationEventInfo; onBeforeLoad: { type: 'onBeforeLoad'; } & NavigationEventInfo; onLoad: { type: 'onLoad'; } & NavigationEventInfo; onResolved: { type: 'onResolved'; } & NavigationEventInfo; onBeforeRouteMount: { type: 'onBeforeRouteMount'; } & NavigationEventInfo; onInjectedHtml: { type: 'onInjectedHtml'; promise: Promise; }; onRendered: { type: 'onRendered'; } & NavigationEventInfo; }; export type RouterEvent = RouterEvents[keyof RouterEvents]; export type ListenerFn = (event: TEvent) => void; export type RouterListener = { eventType: TRouterEvent['type']; fn: ListenerFn; }; export interface MatchRoutesOpts { preload?: boolean; throwOnError?: boolean; _buildLocation?: boolean; dest?: BuildNextOptions; } export type InferRouterContext = TRouteTree['types']['routerContext']; export type RouterContextOptions = AnyContext extends InferRouterContext ? { context?: InferRouterContext; } : { context: InferRouterContext; }; export type RouterConstructorOptions> = Omit, 'context'> & RouterContextOptions; export interface RouterErrorSerializer { serialize: (err: unknown) => TSerializedError; deserialize: (err: TSerializedError) => unknown; } export interface MatchedRoutesResult { matchedRoutes: Array; routeParams: Record; } export type PreloadRouteFn = | string = string, TTo extends string | undefined = undefined, TMaskFrom extends RoutePaths | string = TFrom, TMaskTo extends string = ''>(opts: NavigateOptions, TFrom, TTo, TMaskFrom, TMaskTo>) => Promise | undefined>; export type MatchRouteFn = = '/', TTo extends string | undefined = undefined, TResolved = ResolveRelativePath>>(location: ToOptions, TFrom, TTo>, opts?: MatchRouteOptions) => false | RouteById['types']['allParams']; export type UpdateFn> = (newOptions: RouterConstructorOptions) => void; export type InvalidateFn = (opts?: { filter?: (d: MakeRouteMatchUnion) => boolean; sync?: boolean; }) => Promise; export type ParseLocationFn = (previousLocation?: ParsedLocation>, locationToParse?: HistoryLocation) => ParsedLocation>; export type GetMatchRoutesFn = (next: ParsedLocation, dest?: BuildNextOptions) => { matchedRoutes: Array; routeParams: Record; foundRoute: AnyRoute | undefined; }; export type EmitFn = (routerEvent: RouterEvent) => void; export type LoadFn = (opts?: { sync?: boolean; }) => Promise; export type CommitLocationFn = ({ viewTransition, ignoreBlocker, ...next }: ParsedLocation & CommitLocationOptions) => Promise; export type StartTransitionFn = (fn: () => void) => void; export type SubscribeFn = (eventType: TType, fn: ListenerFn) => () => void; export interface MatchRoutesFn { (pathname: string, locationSearch: AnySchema, opts?: MatchRoutesOpts): Array; (next: ParsedLocation, opts?: MatchRoutesOpts): Array; (pathnameOrNext: string | ParsedLocation, locationSearchOrOpts?: AnySchema | MatchRoutesOpts, opts?: MatchRoutesOpts): Array; } export type GetMatchFn = (matchId: string) => AnyRouteMatch | undefined; export type UpdateMatchFn = (id: string, updater: (match: AnyRouteMatch) => AnyRouteMatch) => AnyRouteMatch; export type LoadRouteChunkFn = (route: AnyRoute) => Promise>; export type ResolveRedirect = (err: AnyRedirect) => ResolvedRedirect; export type ClearCacheFn = (opts?: { filter?: (d: MakeRouteMatchUnion) => boolean; }) => void; export interface ServerSrr { injectedHtml: Array; injectHtml: (getHtml: () => string | Promise) => Promise; injectScript: (getScript: () => string | Promise, opts?: { logScript?: boolean; }) => Promise; streamValue: (key: string, value: any) => void; streamedKeys: Set; onMatchSettled: (opts: { router: AnyRouter; match: AnyRouteMatch; }) => any; } export type AnyRouterWithContext = RouterCore, any, any, any, any>; export type AnyRouter = RouterCore; export interface ViewTransitionOptions { types: Array; } export declare function defaultSerializeError(err: unknown): { name: string; message: string; } | { data: unknown; }; export interface ExtractedBaseEntry { dataType: '__beforeLoadContext' | 'loaderData'; type: string; path: Array; id: number; matchIndex: number; } export interface ExtractedStream extends ExtractedBaseEntry { type: 'stream'; streamState: StreamState; } export interface ExtractedPromise extends ExtractedBaseEntry { type: 'promise'; promiseState: DeferredPromiseState; } export type ExtractedEntry = ExtractedStream | ExtractedPromise; export type StreamState = { promises: Array>; }; export type TrailingSlashOption = 'always' | 'never' | 'preserve'; export declare function getLocationChangeInfo(routerState: { resolvedLocation?: ParsedLocation; location: ParsedLocation; }): { fromLocation: ParsedLocation<{}> | undefined; toLocation: ParsedLocation<{}>; pathChanged: boolean; hrefChanged: boolean; hashChanged: boolean; }; export type CreateRouterFn = = Record>(options: undefined extends number ? 'strictNullChecks must be enabled in tsconfig.json' : RouterConstructorOptions) => RouterCore; export declare class RouterCore = Record> { tempLocationKey: string | undefined; resetNextScroll: boolean; shouldViewTransition?: boolean | ViewTransitionOptions; isViewTransitionTypesSupported?: boolean; subscribers: Set>; viewTransitionPromise?: ControlledPromise; isScrollRestoring: boolean; isScrollRestorationSetup: boolean; __store: Store>; options: PickAsRequired, 'stringifySearch' | 'parseSearch' | 'context'>; history: TRouterHistory; latestLocation: ParsedLocation>; basepath: string; routeTree: TRouteTree; routesById: RoutesById; routesByPath: RoutesByPath; flatRoutes: Array; isServer: boolean; pathParamsDecodeCharMap?: Map; /** * @deprecated Use the `createRouter` function instead */ constructor(options: RouterConstructorOptions); startTransition: StartTransitionFn; update: UpdateFn; get state(): RouterState>; buildRouteTree: () => void; subscribe: SubscribeFn; emit: EmitFn; parseLocation: ParseLocationFn; resolvePathWithBase: (from: string, path: string) => string; get looseRoutesById(): Record; /** @deprecated use the following signature instead ```ts matchRoutes ( next: ParsedLocation, opts?: { preload?: boolean; throwOnError?: boolean }, ): Array; ``` */ matchRoutes: MatchRoutesFn; private matchRoutesInternal; getMatchedRoutes: GetMatchRoutesFn; cancelMatch: (id: string) => void; cancelMatches: () => void; buildLocation: BuildLocationFn; commitLocationPromise: undefined | ControlledPromise; commitLocation: CommitLocationFn; buildAndCommitLocation: ({ replace, resetScroll, hashScrollIntoView, viewTransition, ignoreBlocker, href, ...rest }?: BuildNextOptions & CommitLocationOptions) => Promise; navigate: NavigateFn; latestLoadPromise: undefined | Promise; load: LoadFn; startViewTransition: (fn: () => Promise) => void; updateMatch: UpdateMatchFn; getMatch: GetMatchFn; loadMatches: ({ location, matches, preload: allPreload, onReady, updateMatch, sync, }: { location: ParsedLocation; matches: Array; preload?: boolean; onReady?: () => Promise; updateMatch?: (id: string, updater: (match: AnyRouteMatch) => AnyRouteMatch) => void; getMatch?: (matchId: string) => AnyRouteMatch | undefined; sync?: boolean; }) => Promise>; invalidate: InvalidateFn>; resolveRedirect: (err: AnyRedirect) => ResolvedRedirect; clearCache: ClearCacheFn; clearExpiredCache: () => void; loadRouteChunk: (route: AnyRoute) => Promise; preloadRoute: PreloadRouteFn; matchRoute: MatchRouteFn; ssr?: { manifest: Manifest | undefined; serializer: StartSerializer; }; serverSsr?: { injectedHtml: Array; injectHtml: (getHtml: () => string | Promise) => Promise; injectScript: (getScript: () => string | Promise, opts?: { logScript?: boolean; }) => Promise; streamValue: (key: string, value: any) => void; streamedKeys: Set; onMatchSettled: (opts: { router: AnyRouter; match: AnyRouteMatch; }) => any; }; clientSsr?: { getStreamedValue: (key: string) => T | undefined; }; _handleNotFound: (matches: Array, err: NotFoundError, { updateMatch, }?: { updateMatch?: (id: string, updater: (match: AnyRouteMatch) => AnyRouteMatch) => void; }) => void; hasNotFoundMatch: () => boolean; } export declare class SearchParamError extends Error { } export declare class PathParamError extends Error { } export declare function lazyFn) => any>, TKey extends keyof T = 'default'>(fn: () => Promise, key?: TKey): (...args: Parameters) => Promise>>; export declare function getInitialRouterState(location: ParsedLocation): RouterState; export declare const componentTypes: readonly ["component", "errorComponent", "pendingComponent", "notFoundComponent"]; export {};