radix3

library1.1.2jsnpmunverified

Radix3 is a lightweight and high-performance routing library for JavaScript and TypeScript, currently stable at version 1.1.2. It implements a Radix Tree data structure to offer efficient route matching, making it particularly well-suited for server-side applications, API gateways, and edge runtimes where request routing speed is critical. The library maintains an active development cadence, with regular minor releases introducing enhancements and performance improvements, as seen in the recent updates to v0.8.x and v1.x. Its key differentiators include its minimal footprint, speed, and robust support for various route patterns like named parameters, wildcards, and regex-like segments. It also provides utilities for exporting and rehydrating route matchers, enabling pre-compiled routing logic for faster startup times. Radix3 ships with full TypeScript type definitions, ensuring a strong developer experience.

http-networking web-framework

npm install radix3

github ↗package ↗

INSTALL

IMPORT

SIG · RADIX3

radix3

http-networkingjavascriptv1.1.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createRouter

✓ import { createRouter } from 'radix3';

✗ const createRouter = require('radix3');

While CommonJS `require` works, ESM `import` is the preferred modern syntax and offers better static analysis.

toRouteMatcher

✓ import { createRouter, toRouteMatcher } from 'radix3';

✗ import toRouteMatcher from 'radix3/matcher';

All public utilities are exported from the main 'radix3' package entry point. Sub-path imports are not recommended.

exportMatcher, createMatcherFromExport

✓ import { exportMatcher, createMatcherFromExport } from 'radix3';

✗ const { exportMatcher } = require('radix3').matcher;

Ensure you import both `exportMatcher` and `createMatcherFromExport` from the top-level package.

Demonstrates creating a Radix3 router, inserting various route patterns (static, named, wildcard), performing lookups, and utilizing the `toRouteMatcher` and `exportMatcher` utilities for advanced matching and persistence.

import { createRouter, toRouteMatcher, exportMatcher, createMatcherFromExport } from 'radix3'; // 1. Create a router instance and add routes const router = createRouter({ strictTrailingSlash: false, routes: { '/': { name: 'home' }, '/users': { name: 'users-list' }, '/users/:id': { name: 'user-detail' }, '/assets/**': { name: 'static-assets' }, '/docs/:version/**': { name: 'docs-wildcard' } } }); // 2. Lookup routes console.log('Matching /users:', router.lookup('/users')); // Expected: { name: 'users-list' } console.log('Matching /users/123:', router.lookup('/users/123')); // Expected: { name: 'user-detail', params: { id: '123' } } console.log('Matching /assets/img/logo.png:', router.lookup('/assets/img/logo.png')); // Expected: { name: 'static-assets' } // 3. Create a multi-matcher to find all matching routes const matcher = toRouteMatcher(router); const allMatches = matcher.matchAll('/docs/v1/introduction'); console.log('All matches for /docs/v1/introduction:', allMatches.map(m => m.name)); // Expected: ['docs-wildcard'] // 4. Export and rehydrate matcher for persistence/pre-compilation const exportedMatcher = exportMatcher(matcher); // In a real scenario, `exportedMatcher` would be serialized (e.g., to JSON) and loaded later. const rehydratedMatcher = createMatcherFromExport(exportedMatcher); console.log('Rehydrated matcher matching /users:', rehydratedMatcher.matchAll('/users').map(m => m.name)); // Expected: ['users-list']

Debug

Known issues

breakingThe `url pattern compatibility` was introduced in `v0.8.0`, potentially changing how routes are matched or defined. Review your route patterns when upgrading from `v0.7.x`.

fix

Consult the `radix3` documentation on 'Route Patterns' to understand the updated compatibility rules and adjust your route definitions as necessary.

affects: >=0.8.0

gotchaThe `data` object inserted with `router.insert(path, data)` should not contain a key named `params`, as this is a reserved keyword used by the router for matched route parameters.

fix

Rename any `params` key within your route's `data` object to avoid conflicts, e.g., `payload.params` or `customParams`.

affects: >=0.7.0

gotchaBy default, `radix3` ignores trailing slashes for matching and adding routes. If strict trailing slash matching is required, you must explicitly enable it.

fix

Initialize the router with `createRouter({ strictTrailingSlash: true })` to enable strict trailing slash behavior.

affects: >=0.7.0

gotchaSpecial characters like `:` (for named parameters) and `*` (for wildcards) in a path need to be escaped with a backslash if they are intended to be part of the literal path segment, not a special route pattern.

fix

Use `\:` to match a literal colon and `\*` to match a literal asterisk in your route definition paths.

affects: >=0.7.12

Errors

Common errors & fixes

TypeError: createRouter is not a function

Attempting to use CommonJS `require` syntax when the project or specific file is configured for ESM, or vice-versa.

fix

Ensure your import statement matches your module system. For ESM, use `import { createRouter } from 'radix3';`. For CommonJS, use `const { createRouter } = require('radix3');`.

Route lookup for '/foo/' unexpectedly matches '/foo' when strictTrailingSlash is true.

The `strictTrailingSlash` option was not correctly applied during router initialization or a new router instance was created without it.

fix

Ensure the router is initialized with `{ strictTrailingSlash: true }` when `createRouter()` is called, and that you are using this specific router instance for lookups.

Unexpected route matching or no match for path containing characters like ':', '*', or '**'

Special characters like `:` and `*` are interpreted as route parameters or wildcards by `radix3`.

fix

If these characters are part of a literal path segment and not intended as route patterns, they must be escaped using a backslash, e.g., `/api\:version` or `/files\*`.

Upgrade

Version history

1.1.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/unjs/radix3 ↗

packagehttps://www.npmjs.com/package/radix3 ↗