Client-Side Router & Radix Tree Matching
Client routers intercept link clicks, match paths against a compressed radix tree in O(k) character steps, and coordinate parallel data loaders with AbortController. They synchronize UI state with the URL as State Store without full-document reloads.
Radix Tree Matching & Loader Cancellation
Trace how a client router matches segments in O(k), aborts stale loaders, and commits history.
User clicks /users/99/billing; router prevents full document reload and splits path segments.
e.preventDefault();
router.navigate('/users/99/billing');- targetPath
- /users/99/billing
- segments
- [ "users", "99", "billing" ]
Under the Hood
A radix tree (compressed trie) merges shared path prefixes into single edges, avoiding O(N) regular-expression scans across hundreds of routes.
- Prefix Compression: Routes like
/users/:id/settingsand/users/:id/billingshare the/users/static node and:iddynamic parameter node, branching only at the final segment. - Parallel Loader Dispatch: Once the matched route branch is resolved, the router invokes all nested layout loaders concurrently with a shared
AbortSignal. - Commit & Focus Restoration: When loaders resolve, the router calls
history.pushState(orNavigation.intercept()), updates the component tree, and moves focus to the active landmark.
function matchRadix(node: RouteNode, segments: string[], i = 0, params: Record<string, string> = {}) {
if (i === segments.length) return node.handler ? { handler: node.handler, params } : null;
const seg = segments[i];
const staticChild = node.staticChildren.get(seg);
if (staticChild) return matchRadix(staticChild, segments, i + 1, params);
if (node.paramChild) {
params[node.paramChild.paramName] = seg;
return matchRadix(node.paramChild, segments, i + 1, params);
}
return node.wildcardChild ? { handler: node.wildcardChild.handler, params } : null;
}Problem Genealogy
- 2014 (Linear Regex Tables): Early routers iterated through 300+
path-to-regexpentries per click, burning 4–8 ms of main-thread time on route transitions. - 2019 (Nested Radix Trees & Parallel Loaders): Routers compiled static/dynamic tries and decoupled data fetching from component render waterfalls.
- 2024 (
URLPattern& Navigation API): Browsers standardized native pattern matching and single-hooknavigateinterception, eliminating custompopstateshims.
Production Pitfalls
- Render-Then-Fetch Waterfalls: Deferring data fetching until child route components mount serializes network round-trips across nested layouts.
- Out-of-Order Navigation Commits: Failing to pass an
AbortSignalto route loaders lets a slow response from/items/1overwrite/items/2after the URL changed.
- When not to use a client-side router: Never ship a 20 KB SPA router for content-heavy marketing or documentation sites with low interactivity; MPA navigation paired with Speculation Rules delivers instant transitions with zero JS hydration cost.
Connections & Logical Next Steps
Client routers serialize route params and search state into the History API and URLPattern.
Rapid link clicks abort in-flight route data loaders via AbortSignal before committing the next tree.
Hover prefetching and Speculation Rules warm route chunks and loader data before navigation commits.