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 are evaluated in insertion order and match complete path boundaries. /products matches /products and /products/42 but not /products-old. Put specific prefixes before broad prefixes.

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. defaultRoute runs when no configured prefix matches.

router.routes = {
    '/products/sale': saleRoute,
    '/products': productsRoute,
    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.

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.

<a href="/products/42" data-pushstate>View product 42</a>

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/mediator navigation metadata.

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

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.

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.

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; 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.

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.