router6

Core router implementation for Router6.

Installation

npm install router6
# or
pnpm add router6
# or
yarn add router6
# or
bun add router6

Quick Start

import { createRouter } from "router6";

const routes = [
  { name: "home", path: "/" },
  { name: "users", path: "/users" },
  { name: "users.profile", path: "/:id" },
];

const router = createRouter(routes);

router.start();
router.navigate("users.profile", { id: "123" });

Essential API

createRouter(routes?, options?, dependencies?)

Creates a new router instance. Wiki

const router = createRouter(
  routes,       // Route[] - route definitions
  options,      // Partial<Options> - router options
  dependencies, // object - dependency injection
);

Lifecycle

router.start(startPath?, done?)

Starts the router. Wiki

router.start();
router.start("/users/123");
router.start("/users/123", (err, state) => {
  if (err) console.error(err);
});

router.stop()

Stops the router. Wiki

router.isStarted()

Returns whether the router is started. Wiki

Navigation

router.navigate(name, params?, options?, done?)

Navigates to a route by name. Returns a cancel function. Wiki

router.navigate("users");
router.navigate("users.profile", { id: "123" });
router.navigate("users.profile", { id: "123" }, { replace: true });

// With callback
router.navigate("users", {}, {}, (err, state) => {
  if (err) console.error(err);
});

// Cancellation
const cancel = router.navigate("users.profile", { id: "123" });
cancel(); // abort navigation

router.getState()

Returns the current router state. Wiki

const state = router.getState();
// { name: "users.profile", params: { id: "123" }, path: "/users/123" }

router.navigateToDefault(options?, done?)

Navigates to the default route. Wiki

Guards

router.canActivate(name, guardFactory)

Registers a guard for route activation. Wiki

router.canActivate("admin", () => (toState, fromState, done) => {
  if (!isAuthenticated()) {
    done({ redirect: { name: "login" } });
  } else {
    done();
  }
});

router.canDeactivate(name, guardFactory)

Registers a guard for route deactivation. Wiki

router.canDeactivate("editor", () => (toState, fromState, done) => {
  if (hasUnsavedChanges()) {
    done({ error: new Error("Unsaved changes") });
  } else {
    done();
  }
});

Events

router.subscribe(listener)

Subscribes to successful transitions. Wiki

const unsubscribe = router.subscribe(({ route, previousRoute }) => {
  console.log("Navigation:", previousRoute?.name, "→", route.name);
});

router.addEventListener(event, listener)

Adds an event listener. Returns an unsubscribe function. Wiki

import { events } from "router6";

router.addEventListener(events.TRANSITION_START, (toState, fromState) => {
  console.log("Starting:", toState.name);
});

// Available events:
// ROUTER_START, ROUTER_STOP
// TRANSITION_START, TRANSITION_SUCCESS, TRANSITION_ERROR, TRANSITION_CANCEL

Plugins

router.usePlugin(pluginFactory)

Registers a plugin. Returns an unsubscribe function. Wiki

import { browserPlugin } from "router6-plugin-browser";

const unsubscribe = router.usePlugin(browserPlugin());

Middleware

router.useMiddleware(middlewareFactory)

Registers middleware for the navigation pipeline. Wiki

router.useMiddleware((router) => (toState, fromState, done) => {
  console.log("Navigating:", toState.name);
  done();
});

Advanced API

Routes

router.addRoute(route: Route): void

Add a route definition at runtime.
Wiki

router.removeRoute(name: string): void

Remove a route by name.
Wiki

router.getRoute(name: string): Route | undefined

Get route definition by name.
Wiki

router.hasRoute(name: string): boolean

Check if a route exists.
Wiki

router.clearRoutes(): void

Remove all routes.
Wiki

router.forward(fromRoute: string, toRoute: string): void

Set up route forwarding (redirect).
Wiki

State Utilities

router.getPreviousState(): State | undefined

Get previous router state.
Wiki

router.setState(state: State): void

Set state directly without navigation.
Wiki

router.makeState(name: string, params?, path?, meta?): State

Create a state object.
Wiki

router.buildState(name: string, params?): State | undefined

Build state from route name.
Wiki

router.areStatesEqual(state1, state2, ignoreQueryParams?): boolean

Compare two states for equality.
Wiki

router.areStatesDescendants(parentState, childState): boolean

Check if child state is descendant of parent.
Wiki

Path Operations

router.buildPath(name: string, params?): string

Build URL path from route name.
Wiki

router.matchPath(path: string): State | undefined

Match URL path to state.
Wiki

router.isActiveRoute(name, params?, strictEquality?, ignoreQueryParams?): boolean

Check if route is currently active.
Wiki

router.setRootPath(rootPath: string): void

Set root path prefix for all routes.
Wiki

Dependencies

router.getDependencies(): Dependencies

Get all dependencies.
Wiki

router.setDependency(name: string, value: unknown): void

Set a dependency.
Wiki

router.getDependency(name: string): unknown

Get a dependency by name.
Wiki

Options

router.getOptions(): Options

Get router options.
Wiki

router.setOption(name: string, value: unknown): void

Set a router option. Must be called before start().
Wiki

Other

router.clone(dependencies?): Router

Clone router for SSR.
Wiki

router.isNavigating(): boolean

Check if navigation is in progress.
Wiki

router.clearMiddleware(): void

Clear all middleware.
Wiki

router.clearCanActivate(name: string): void

Clear activation guard for a route.
Wiki

router.clearCanDeactivate(name: string): void

Clear deactivation guard for a route.
Wiki

Configuration

interface Options {
  defaultRoute: string;            // Default route name (default: "")
  defaultParams: Params;           // Default route params (default: {})
  trailingSlash: "strict" | "never" | "always" | "preserve";  // (default: "preserve")
  caseSensitive: boolean;          // Case-sensitive matching (default: false)
  urlParamsEncoding: "default" | "uri" | "uriComponent" | "none";  // (default: "default")
  queryParamsMode: "default" | "strict" | "loose";  // (default: "loose")
  queryParams?: QueryParamsOptions; // Query parameter parsing options
  allowNotFound: boolean;          // Allow navigation to unknown routes (default: true)
  rewritePathOnMatch: boolean;     // Rewrite path on successful match (default: false)
}

See RouterOptions for detailed documentation.

Observable Support

The router implements the TC39 Observable interface:

import { from } from "rxjs";

from(router).subscribe(({ route, previousRoute }) => {
  console.log("Route changed:", route.name);
});

See Symbol.observable for details.

Error Handling

Navigation errors are instances of RouterError:

import { RouterError, errorCodes } from "router6";

router.navigate("users", {}, {}, (err, state) => {
  if (err instanceof RouterError) {
    console.log(err.code, err.message);
  }
});

| Code | Description | | ------------------- | ------------------------------ | | ROUTE_NOT_FOUND | Route doesn't exist | | CANNOT_ACTIVATE | Blocked by canActivate guard | | CANNOT_DEACTIVATE | Blocked by canDeactivate guard | | CANCELLED | Navigation was cancelled | | SAME_STATES | Already at target route | | NOT_STARTED | Router not started | | ALREADY_STARTED | Router already started |

See RouterError and Error Codes for details.

Documentation

Full documentation on Wiki:

• createRouter — factory function
• start · stop — lifecycle
• navigate — navigation
• State — state type
• Route — route definition
• Plugins — plugin system
• Middleware — middleware system

Related Packages

• router6-react — React integration
• router6-plugin-browser — Browser history
• router6-plugin-logger — Debug logging
• router6-plugin-persistent-params — Persistent params
• router6-helpers — Utilities

License

MIT © Oleg Ivanov