# @zerolith/router Import from `@zerolith/router`. Generated from the source; every signature below is what the published types declare. ## Functions ### createRouter ```ts function createRouter(routes: T, options?: RouterOptions): Router ``` Creates a router over the given table and attaches it to the window when one exists. Source: `packages/router/src/router.ts:273` ### defineRoutes ```ts function defineRoutes(routes: T): T ``` Declares the route table, preserving every name and path for `href()`; it returns its argument. Source: `packages/router/src/router.ts:85` ### lazy ```ts function lazy(loader: () => Promise>): LazyView ``` Marks a view to be imported on first navigation. Source: `packages/router/src/router.ts:91` ### route ```ts function route(definition: RouteDefinition): RouteDefinition ``` Declares one route, inferring its parameters from the path and its data from the loader. Source: `packages/router/src/router.ts:63` ## Interfaces ### AnyRoute ```ts interface AnyRoute ``` The loose shape every route satisfies, used to constrain tables without losing each entry's own types. - `readonly path: string`: The route's path pattern; `href()` takes the types of its parameters from it. - `readonly view: unknown`: The route's view function or `lazy()` view. - `readonly load?: unknown`: The route's loader, when it has one. - `readonly head?: unknown`: The route's document metadata or the function that computes it, when it has one. Source: `packages/router/src/router.ts:69` ### Head ```ts interface Head ``` Document metadata a route contributes. - `title?: string`: The document title, set as `document.title` in the browser and rendered as `` by `renderHead`; `undefined` leaves the title as it is. - `description?: string`: The page description, the content of `<meta name="description">`; `undefined` leaves it as it is. In the browser the router adds that element when the document lacks one. Source: `packages/router/src/router.ts:9` ### LazyView ```ts interface LazyView<Params, Data> ``` A view resolved on first navigation, created with `lazy()`. - `readonly lazy: () => Promise<RouteView<Params, Data>>`: Imports the view; the router calls it on the first navigation to the route and keeps the view it resolves. Source: `packages/router/src/router.ts:43` ### LoadContext ```ts interface LoadContext<Params> ``` What a route's `load` receives. - `params: Params`: The path parameters by name, decoded from the URL. - `url: URL`: The URL being navigated to, query and hash included; the router's `url` changes to it only when the navigation commits. - `abort: AbortSignal`: Aborted when a newer navigation starts. Source: `packages/router/src/router.ts:18` ### Match ```ts interface Match ``` The route the URL resolved to. - `readonly name: string`: The matched route's name in the route table. - `readonly params: Readonly<Record<string, string>>`: The path parameters by name, decoded from the URL; empty when the path has none. - `readonly url: URL`: The URL the route matched, query and hash included. - `readonly data: unknown`: What the route's `load` resolved to, or on the initial navigation the copy the server embedded; `undefined` when the route has no loader. Source: `packages/router/src/router.ts:97` ### NavigationEvent ```ts interface NavigationEvent ``` What `observe` receives: a navigation starting, then committing, failing, or canceled because a newer navigation started before it committed or the router was disposed, with one id per navigation. - `readonly type: "start" | "commit" | "error" | "cancel"`: The stage: `start` when the navigation begins, then one of `commit`, `error`, or `cancel` when it ends. - `readonly id: number`: The same number for the start and the end of one navigation. - `readonly url: URL`: The URL being navigated to. - `readonly mode: "push" | "replace" | "pop"`: How the navigation arrived: `push` adds a history entry, `replace` overwrites the current one, as the initial navigation does, and `pop` follows back or forward in the browser. - `readonly name?: string | undefined`: The matched route's name on commit; undefined when the fallback rendered. - `readonly error?: unknown`: The loader's error on failure. Source: `packages/router/src/router.ts:117` ### RouteContext ```ts interface RouteContext<Params, Data> ``` What a route's `view` and `head` receive. - `params: Params`: The path parameters by name, decoded from the URL. - `data: Data`: What the route's `load` resolved to, or on the initial navigation the copy the server embedded; `undefined` when the route has no loader. - `url: URL`: The URL the route matched, query and hash included. Source: `packages/router/src/router.ts:29` ### RouteDefinition ```ts interface RouteDefinition<Path extends string = string, Data = undefined> ``` One entry of the route table. Write `load` before `view` so the data type flows into the view. - `path: Path`: The path pattern, relative to the router's `base`: static segments, `:name` parameters, and an optional trailing `*rest` that captures the remainder. - `view: RouteView<ParamsOf<Path>, Data> | LazyView<ParamsOf<Path>, Data>`: Renders the route: a view function, or a `lazy()` view imported on first navigation. - `load?: (context: LoadContext<ParamsOf<Path>>) => Promise<Data>`: Resolves the data `view` and `head` receive, before the URL changes; the initial navigation skips it when the server embedded data for the same route, path, and query. - `head?: Head | ((context: RouteContext<ParamsOf<Path>, Data>) => Head)`: The route's document metadata: an object, or a function that receives the route context once `load` resolves. Source: `packages/router/src/router.ts:50` ### Router ```ts interface Router<T extends RouteTable> ``` The router returned by `createRouter`, typed by its route table. - `readonly current: ReadableSignal<Match | undefined>`: The current match, or undefined when nothing matched (the fallback renders). - `readonly url: ReadableSignal<URL>`: The current URL. - `readonly pending: ReadableSignal<boolean>`: True while a navigation is loading. - `readonly head: ReadableSignal<Head>`: The head metadata of the current route, for the server to render and for the browser to apply. - `readonly ready: Promise<void>`: Settles when the initial navigation from the window's location has committed; already settled without a window. Rejects as `navigate` would. - `href<N extends keyof T & string>(name: N, ...args: HrefArgs<T[N]["path"]>): string`: Builds a URL path for a named route. - `navigate(to: string, options?: { replace?: boolean }): Promise<void>`: Navigates to a path or URL, running the route's loader first. A URL on another origin is left to the browser, through `location.assign`, or `location.replace` with `replace`. - `matches(path: string, options?: { exact?: boolean }): ReadableSignal<boolean>`: A signal that is true while the URL is at `path` or below it; `exact` requires equality. - `outlet(): View`: Renders the current route, used as `${router.outlet()}`. - `dispose(): void`: Detaches the router from the window. Source: `packages/router/src/router.ts:167` ### RouterOptions ```ts interface RouterOptions ``` Options for `createRouter`. - `fallback?: (url: URL) => unknown`: Renders when no route matches. - `onError?: (error: unknown, url: URL) => void`: Called when a loader, a lazy import, or a route's `head` throws, or when the new page throws as it renders. Without it the error propagates from `navigate()`. - `scroll?: boolean`: Set false to leave scrolling to the application. Defaults to true. - `window?: Window | null`: The window to attach to. Defaults to the global window; `null` attaches to none, as on the server, even where a window exists. - `observe?: (event: NavigationEvent) => void`: Receives one event when a navigation starts and one when it commits, fails, or is canceled by a newer navigation or by `dispose()`; the hook tracing and logging attach to. - `base?: string`: The path the application is served under, such as `"/app/"`, or `import.meta.env.BASE_URL` to follow the build. Route paths are relative to it, `href()` includes it, and links outside it are left to the browser. Defaults to `"/"`; a relative base such as `"./"` counts as `"/"`. Source: `packages/router/src/router.ts:134` ### EmbeddedRouteState ```ts interface EmbeddedRouteState ``` What `renderRouteState` embeds: the route the server rendered, its URL, and the data its loader produced. - `readonly name: string`: The name of the route the server rendered; the browser reuses `data` only when its initial navigation matches the same route. - `readonly href: string`: The path and query of the URL the server rendered; the browser reuses `data` only when its initial URL has the same ones. - `readonly data: unknown`: What the route's loader produced on the server, embedded as JSON. Source: `packages/router/src/router.ts:212` ## Types ### ParamsOf ```ts type ParamsOf<Path extends string> = Path extends `${infer Head}/${infer Rest}` ? ParamsOf<Head> & ParamsOf<Rest> : Path extends `:${infer Name}` ? { [K in Name]: string } : Path extends `*${infer Name}` ? { [K in Name]: string } : {} ``` The parameter names in a path pattern, derived at the type level. Source: `packages/router/src/match.ts:7` ### HrefArgs ```ts type HrefArgs<Path extends string> = Record<string, never> extends ParamsOf<Path> ? [] : [ParamsOf<Path>] ``` The arguments `href()` takes for a path: none when it has no parameters. Source: `packages/router/src/router.ts:110` ### RouteTable ```ts type RouteTable = Readonly<Record<string, AnyRoute>> ``` A route table: route names to `route()` definitions. Source: `packages/router/src/router.ts:82` ### RouteView ```ts type RouteView<Params, Data> = (context: RouteContext<Params, Data>) => unknown ``` Renders a route. Called once per navigation to that route. Source: `packages/router/src/router.ts:40` ## Constants ### ROUTE_STATE_SELECTOR ```ts const ROUTE_STATE_SELECTOR: string ``` The selector of the script `renderRouteState` writes. Source: `packages/router/src/router.ts:223`