white-label-router

Install and requirements

• Node.js ^22.18.0 or >=24.11.0
• Browser History API/location/DOM events only for browser enhancement
• Directly requestable server routes for public browser URLs

import Router from 'white-label-router';

const router = new Router();

Route definitions and matching

Routes match complete path boundaries. /products matches /products and /products/42 but not /products-old. When more than one own route prefix matches, Router selects the longest matching prefix so the most specific route wins regardless of declaration order.

A route can be a function or an object with title, focus, secure, and view lifecycle fields. secure() must return exactly true to allow navigation. Router pairs a successfully initialized object-view lifecycle with the exact destroy callback that owned it, even if route configuration is later replaced or mutated. defaultRoute runs when no configured prefix matches.

router.routes = {
    '/products': productsRoute,
    '/products/sale': saleRoute,
    defaultRoute
};

Progressive enhancement

Browser navigation should start with a real anchor. data-pushstate opts eligible same-origin links into client-side navigation. Modified clicks, non-left clicks, downloads, alternate targets, and cross-origin URLs stay native.

By default opted-in clicks are observed across document. Set navigationRoot to a Document or Element to scope interception to an owned region; reassigning it while active moves the click listener, and null restores document-wide behavior. navigationRoot is separate from callback scope.

Initialization dispatches the current URL without creating a duplicate history entry. Back/forward navigation reads the authoritative window.location rather than trusting arbitrary history state.

const router = new Router();
router.navigationRoot = document.querySelector('[data-product-refinements]');
router.initialize();

Location payload

Route callbacks receive scope and a location object. data.url contains decoded path segments after the matched prefix, data.query contains the last value for each query key, and data.mediator contains programmatic navigation metadata or router:navigate CustomEvent.detail.

Applications remain responsible for validating decoded URL values before using them as trusted domain data.

{
  url: '/products/42?color=blue',
  data: {
    url: ['42'],
    query: {color: 'blue'},
    mediator: {source: 'featured'}
  }
}

Route lifecycle, title, and focus

Router validates the destination guard and runnable view behavior before tearing down the current route. On a successful route change, the previous route view's destroy() runs before the next view's initialize(). Browser object routes can update document title and focus after rendering.

Rejected navigation preserves the last successful URL, route/location state, current route lifecycle, and browser history. The default focus selector is main h1; set focus: false when navigation represents an in-page refinement that should preserve focus. Server runtimes keep pageTitle state but do not mutate a document or focus target.

Serverless routing

Pass the incoming request URL explicitly to Router in a serverless function. The server path uses the same route matching, query parsing, guards, and lifecycle contract without requiring window or document.

Scope mutable Router state to the request unless sharing is deliberate. Router handles application routing inside an invocation; it does not replace API Gateway, platform routes, CDN rules, or other cloud request routing.

const router = new Router();
router.routes = routes;
router.navigate(new URL(request.url).pathname);

Related guides

Focused guides for common implementation questions around this package.

• Progressive-enhancement routing in TypeScript

TypeScript

Router.Route, Router.Location, Router.Navigation, and Router.Handler expose the supported public route contracts.

DOM types are present because the same class supports browser scopes/events and Document/Element navigation roots; server hosts do not need DOM globals at runtime.

Security and trust boundaries

URL and query values are decoded, not trusted. Validate them before using them for authorization, data access, or domain decisions.

route.secure is an application guard hook; Router does not implement authentication policy.

Malformed navigation candidates are rejected with false before Router state changes. Server adapters should preserve raw request-target path semantics and hand Router a fully qualified URL.

Design boundaries

Router owns URL-to-intent translation. It does not own state, rendering, data loading, authentication policy, or server infrastructure.

Real links and directly requestable server URLs remain the foundation; Router enhances them instead of replacing them. navigationRoot limits interception ownership; callback scope remains application data.