Browse documentation

Router

Coordinates route definitions and resolves navigation through the public router flow.

Table of contents

Category

Value

Import

js
import { Router } from "valyrian.js/router";

Public signature

ts
new Router(pathPrefix?: string): Router

API form

Router is a class. Create one instance, register routes and catch handlers, then pass it to mountRouter(...) in the browser or call go(...) during server rendering.

Constructor and route request

ts
const router = new Router(pathPrefix?);

type Request = {
  path: string;
  url: string;
  params: Record<string, unknown>;
  query: Record<string, unknown>;
  matches: string[];
  redirect(path: string): Promise<string | void>;
};

Defaults and properties

Omitting pathPrefix creates an unprefixed router. Public navigation state is available through container, path, url, params, query, matches and pathPrefix.

Essential methods

ts
type RouteCallback = (
  nextRoute: { path: string; query: Record<string, unknown>; params: Record<string, unknown> },
  currentRoute: { path: string; query: Record<string, unknown>; params: Record<string, unknown> } | null,
) => boolean | void | Promise<boolean | void>;

type RouteParams =
  | string
  | Middleware
  | Router
  | Array<string | Middleware | Router | RouteParams>;

add(...args: RouteParams[]): Router
catch(...args: Array<number | string | Error | typeof Error | Middleware>): Router
routes(): string[]
go(path: string, parentComponent?): Promise<string | void>
beforeRoute(callback: RouteCallback): () => void
afterRoute(callback: RouteCallback): () => void
getOnClickHandler(url: string): (event: MouseEvent) => void

Route outcomes

Middleware returns a component or vnode to resolve, false to cancel, or undefined to continue. Route hooks return an unsubscribe function. Register exact routes before dynamic and wildcard routes because registration order controls matching.

Errors

Router operations reject invalid middleware, invalid error conditions, circular error handling and subrouter misuse with RouterError.