@thi.ng/router

[!NOTE] This is one of 208 standalone projects, maintained as part of the @thi.ng/umbrella monorepo and anti-framework.

🚀 Please help me to work full-time on these projects by sponsoring me on GitHub. Thank you! ❤️

• About
• Status
• Related packages
• Installation
• Dependencies
• Usage examples
• API
• Benchmarks
• Authors
• License

About

Generic trie-based router with support for wildcards, route param validation/coercion, auth.

• Not bound to any environment, usable on both client & server side
• Declarative route definitions, incl. wildcards for matching rest args
• Parametric routes, each param with optional value coercion & validation
• Route authentication handler to enable/disable routes based on other state factors
• Fallback route redirect
• Enforced initial route (optional)
• Route formatting (with params & rest args)
• Optional HTML5 history & hash fragment support

Status

STABLE - used in production

Search or submit any issues for this package

Related packages

• @thi.ng/hdom - Lightweight vanilla ES6 UI component trees with customizable branch-local behaviors
• @thi.ng/rdom - Lightweight, reactive, VDOM-less UI/DOM components with async lifecycle and @thi.ng/hiccup compatible

Installation

yarn add @thi.ng/router

ESM import:

import * as rou from "@thi.ng/router";

Browser ESM import:

<script type="module" src="https://esm.run/@thi.ng/router"></script>

JSDelivr documentation

Package sizes (brotli'd, pre-treeshake): ESM: 1.94 KB

Dependencies

• @thi.ng/api
• @thi.ng/checks
• @thi.ng/equiv
• @thi.ng/errors
• tslib

Note: @thi.ng/api is in most cases a type-only import (not used at runtime)

Usage examples

Two projects in this repo's /examples directory are using this package:

Screenshot	Description	Live demo	Source
	Basic thi.ng/router usage with thi.ng/rdom components	Demo	Source
	Complete mini SPA app w/ router & async content loading	Demo	Source

API

Generated API docs

import {
    HTMLRouter, HTMLRouterOpts, EVENT_ROUTE_CHANGED,
} from "@thi.ng/router";
import { isUUID } from "@thi.ng/checks";

// router configuration
const config: HTMLRouterOpts = {
    // use hash fragment for routes
    useFragment: true,

    // fallback route (when no other matches)
    default: "home",

    // optional enforced route when router starts
    initial: "home",

    // Optional route path component separator. Default: `/`
    separator: "/",

    // Route prefix. Default: `/` (or `#/` if `useFragment` is enabled).
    // All routes to be parsed by `route()` are assumed to have this prefix.
    // All routes returned by `format()` will include this prefix.
    prefix: "#/",

    // actual route defs
    // An array of route specs which route input strings will be matched against.
    // Given routes will be pre-processed and stored in a Trie for fast matching.
    // Additional routes can be dynamically added at a later time via .addRoutes()
    routes: [
        {
            // each route MUST have an ID
            id: "home",
            // this array defines the route path items
            match: "/home",
        },
        {
            id: "user-profile",
            // this rule is parametric
            // variable items are prefixed with `?`
            match: "/users/?id",
            // coercion & validation handlers for "?id" param
            // coercion fn is applied BEFORE validator
            validate: {
                id: {
                    coerce: (x) => parseInt(x),
                    check: (x) => x > 0 && x < 100,
                },
            },
        },
        {
            id: "image",
            // this route has 2 params and matches (for example):
            // "/images/07a9d87b-c07a-42e3-82cf-baea2f94facc/xl"
            match: "/images/?id/?size",
            validate: {
                id: {
                    check: (x) => isUUID(x),
                },
                size: {
                    check: (x) => /^(s|m|l|xl)$/.test(x),
                },
            },
        },
        {
            id: "group-list",
            // matches only: "/users" or "/images"
            match: "/?type",
            validate: {
                type: {
                    check: (x) => /^(users|images)$/.test(x),
                },
            },
        },
    ],
};

// `HTMLRouter` ONLY works in browser environments
// for non-browser use cases use `Router`
const router = new HTMLRouter(config);
router.addListener(EVENT_ROUTE_CHANGED, console.log);

router.start();

Benchmarks

The below benchmarks are ported from router-benchmark, showing highly competitive results for this package. The benchmark itself can be run from the repo root like so:

bun packages/router/bench/index.ts

benchmarking: short static
        warmup... 133.48ms (0.1 runs)
        total: 113.79ms, runs: 1 (@ 1 calls/iter)
        freq: 8788202.11 ops/sec

benchmarking: static with same radix
        warmup... 166.98ms (0.1 runs)
        total: 161.89ms, runs: 1 (@ 1 calls/iter)
        freq: 6176873.20 ops/sec

benchmarking: dynamic route
        warmup... 378.30ms (0.1 runs)
        total: 374.80ms, runs: 1 (@ 1 calls/iter)
        freq: 2668082.83 ops/sec

benchmarking: mixed static dynamic
        warmup... 344.19ms (0.1 runs)
        total: 340.33ms, runs: 1 (@ 1 calls/iter)
        freq: 2938310.18 ops/sec

benchmarking: long static
        warmup... 326.61ms (0.1 runs)
        total: 327.84ms, runs: 1 (@ 1 calls/iter)
        freq: 3050259.51 ops/sec

benchmarking: wildcard
        warmup... 207.84ms (0.1 runs)
        total: 207.49ms, runs: 1 (@ 1 calls/iter)
        freq: 4819484.22 ops/sec

benchmarking: all together
        warmup... 1525.05ms (0.1 runs)
        total: 1532.24ms, runs: 1 (@ 1 calls/iter)
        freq: 652640.66 ops/sec

Authors

• Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

@misc{thing-router,
  title = "@thi.ng/router",
  author = "Karsten Schmidt",
  note = "https://thi.ng/router",
  year = 2014
}

License

© 2014 - 2025 Karsten Schmidt // Apache License 2.0