eze-router

Lightweight React router built on the browser History API with Hive-style reactive state.

pnpm add eze-router

Features

• Zero-dependency routing — uses history.pushState / popstate directly
• Reactive hooks — useLocation, useQuery, usePathParams powered by createHook
• Lazy routes — React.lazy + Suspense for code-split pages
• Wildcard routes — /files/* matches any sub-path
• Navigation guards — beforeLeave and navigationGuard callbacks
• Permissions — route-level permission gating via PermissionsAdapterBase
• Filtered route tree — engine.allowedRoutes is stable and safe for menus
• Context-based — no singleton; consumer creates their own engine instance
• RouterProvider — wraps the app and provides the engine via React Context
• Link component — respects modifier keys (cmd+click → new tab)

Quick Start

import { RouterEngineClass, RoutesRenderer, RouterProvider } from "eze-router";

const engine = new RouterEngineClass();

const routes = [
  { path: "/", page: HomePage },
  { path: "/about", lazyPage: () => import("./About") },
  { path: "/users/:id", lazyPage: () => import("./UserProfile") },
  { path: "/files/*", page: FileBrowser },
];

function App() {
  return (
    <RouterProvider engine={engine}>
      <RoutesRenderer routes={routes} redirect={NotFound} />
    </RouterProvider>
  );
}

API

| Surface | Description | | ----------------------------- | --------------------------------------------------- | | RouterEngineClass | Router class — create your own instance | | RouterProvider | Context provider for the engine | | RouterContext | React Context (for custom hooks) | | RoutesRenderer | Component that renders the active route | | Link | <a> wrapper with SPA navigation | | QueryListener | Component that re-renders on query changes | | engine.useLocation() | Hook returning current pathname | | engine.useQuery() | Hook returning parsed query params | | engine.usePathParams() | Hook returning matched path params | | engine.navigate(to, replace?) | Navigate and return true; return false when a guard blocks it | | engine.allowedRoutes | Permission-filtered route tree in declaration order | | engine.setQueryParams(q, replace?) | Update query string | | engine.setBeforeLeave(fn) | Set navigation guard (leave confirmation) | | engine.setNavigationGuard(fn) | Set from/to guard | | BrowserHistory | Browser history adapter | | MemoryHistory | In-memory history adapter (SSR/tests) | | matchPath(pattern, path) | Match a path against a pattern | | normalizePath(path) | Normalize slashes and trailing slash | | compilePath(path) | Compile path pattern to regex | | parseQueryString(qs) | Parse query string to object |

Navigation result and void callbacks

engine.navigate(to, replace?) returns true when navigation is accepted and false when beforeLeave or navigationGuard blocks it. When an integration expects a callback that returns void (or void | Promise<void>), use a block body so the boolean is intentionally not returned:

const onClose: () => void = () => {
  engine.navigate("/dashboard");
};