0.1.0-alpha.7

@zerolith/router

Import from @zerolith/router. Generated from the source; every signature below is what the published types declare.

Functions

createRouter

function createRouter<T extends RouteTable>(routes: T, options?: RouterOptions): Router<T>

Creates a router over the given table and attaches it to the window when one exists.

Source: packages/router/src/router.ts:273

defineRoutes

function defineRoutes<T extends RouteTable>(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

function lazy<Params, Data>(loader: () => Promise<RouteView<Params, Data>>): LazyView<Params, Data>

Marks a view to be imported on first navigation.

Source: packages/router/src/router.ts:91

route

function route<Path extends string, Data = undefined>(definition: RouteDefinition<Path, Data>): RouteDefinition<Path, Data>

Declares one route, inferring its parameters from the path and its data from the loader.

Source: packages/router/src/router.ts:63

Interfaces

AnyRoute

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

interface Head

Document metadata a route contributes.

  • title?: string: The document title, set as document.title in the browser and rendered as <title> 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

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

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

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

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

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

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

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

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

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

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

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

type RouteTable = Readonly<Record<string, AnyRoute>>

A route table: route names to route() definitions.

Source: packages/router/src/router.ts:82

RouteView

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

const ROUTE_STATE_SELECTOR: string

The selector of the script renderRouteState writes.

Source: packages/router/src/router.ts:223