lite-trie-router

Ultra-light React router (~2KB min+gzip) built for O(M) URL matching (M = path segments), predictive code-split preloading, and useSyncExternalStore history sync.

Why this router?

| Technique | Benefit | | ----------------------- | ---------------------------------------------------------------- | | Segment trie | Match cost grows with URL depth, not total route count | | Shared import cache | Hover prefetch and click navigation reuse one import() promise | | History patch | pushState / replaceState / popstate all notify React | | Manual path split | No regex on hot path; V8-friendly string scans | | startTransition | Route paint stays responsive during chunk resolution |

Install

npm install lite-trie-router

Peer dependency: React 18+.

Quick start

import { CustomRouter, Link, useParams, useQuery } from "lite-trie-router";

const routes = [
  { path: "/", loadFn: () => import("./pages/Home.jsx") },
  { path: "/dashboard/:userId", loadFn: () => import("./pages/Dashboard.jsx") },
];

export default function App() {
  return (
    <CustomRouter
      routes={routes}
      fallback={<div>404</div>}
      loadingFallback={<div>Loading…</div>}
    >
      <nav>
        <Link to="/dashboard/abc?tab=metrics">Dashboard</Link>
      </nav>
    </CustomRouter>
  );
}

function DashboardPage() {
  const { userId } = useParams();
  const { tab } = useQuery();
  return (
    <h1>
      {userId} — {tab}
    </h1>
  );
}

Note: Place <Link> inside <CustomRouter> so prefetch can access the compiled trie.

API

Components

• CustomRouter — { routes, fallback, loadingFallback?, children? }
• Link — { to, prefetch?, ...anchorProps } — preloads on mouseenter, focus, and touchstart

Hooks

• useParams() — dynamic segments (:id → { id: '42' })
• useQuery() — parsed query object
• useHash() — hash without #
• useLocation() — { pathname, search, hash }

Imperative

import { navigate } from "lite-trie-router";

navigate("/settings", { replace: true });

Low-level (testing / custom integrations)

• createTrieRouter(routes)
• matchTrie(root, pathname, segments?)
• parseUrl(url)
• splitPath(pathname)
• prefetchRoute(routeKey, loadFn)
• clearRouteCache()

Performance tips

1. Use stable routes array reference (or memoize) to avoid rebuilding the trie.
2. Keep loadFn as () => import('./Page') — the library dedupes by route path.
3. Disable prefetch on huge menus: <Link prefetch={false} />.
4. Run npm run bench locally — reports match-only (cached segments) vs split+match.
5. High fanout nodes (48+ sibling routes) auto-switch to Map lookups at compile time.

License

MIT