{"id":11623,"library":"radix3","title":"Radix3 Router","description":"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.","status":"active","version":"1.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/unjs/radix3","tags":["javascript","typescript"],"install":[{"cmd":"npm install radix3","lang":"bash","label":"npm"},{"cmd":"yarn add radix3","lang":"bash","label":"yarn"},{"cmd":"pnpm add radix3","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` works, ESM `import` is the preferred modern syntax and offers better static analysis.","wrong":"const createRouter = require('radix3');","symbol":"createRouter","correct":"import { createRouter } from 'radix3';"},{"note":"All public utilities are exported from the main 'radix3' package entry point. Sub-path imports are not recommended.","wrong":"import toRouteMatcher from 'radix3/matcher';","symbol":"toRouteMatcher","correct":"import { createRouter, toRouteMatcher } from 'radix3';"},{"note":"Ensure you import both `exportMatcher` and `createMatcherFromExport` from the top-level package.","wrong":"const { exportMatcher } = require('radix3').matcher;","symbol":"exportMatcher, createMatcherFromExport","correct":"import { exportMatcher, createMatcherFromExport } from 'radix3';"}],"quickstart":{"code":"import { createRouter, toRouteMatcher, exportMatcher, createMatcherFromExport } from 'radix3';\n\n// 1. Create a router instance and add routes\nconst router = createRouter({\n  strictTrailingSlash: false,\n  routes: {\n    '/': { name: 'home' },\n    '/users': { name: 'users-list' },\n    '/users/:id': { name: 'user-detail' },\n    '/assets/**': { name: 'static-assets' },\n    '/docs/:version/**': { name: 'docs-wildcard' }\n  }\n});\n\n// 2. Lookup routes\nconsole.log('Matching /users:', router.lookup('/users'));\n// Expected: { name: 'users-list' }\n\nconsole.log('Matching /users/123:', router.lookup('/users/123'));\n// Expected: { name: 'user-detail', params: { id: '123' } }\n\nconsole.log('Matching /assets/img/logo.png:', router.lookup('/assets/img/logo.png'));\n// Expected: { name: 'static-assets' }\n\n// 3. Create a multi-matcher to find all matching routes\nconst matcher = toRouteMatcher(router);\nconst allMatches = matcher.matchAll('/docs/v1/introduction');\nconsole.log('All matches for /docs/v1/introduction:', allMatches.map(m => m.name));\n// Expected: ['docs-wildcard']\n\n// 4. Export and rehydrate matcher for persistence/pre-compilation\nconst exportedMatcher = exportMatcher(matcher);\n// In a real scenario, `exportedMatcher` would be serialized (e.g., to JSON) and loaded later.\nconst rehydratedMatcher = createMatcherFromExport(exportedMatcher);\nconsole.log('Rehydrated matcher matching /users:', rehydratedMatcher.matchAll('/users').map(m => m.name));\n// Expected: ['users-list']\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Consult the `radix3` documentation on 'Route Patterns' to understand the updated compatibility rules and adjust your route definitions as necessary.","message":"The `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`.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Rename any `params` key within your route's `data` object to avoid conflicts, e.g., `payload.params` or `customParams`.","message":"The `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.","severity":"gotcha","affected_versions":">=0.7.0"},{"fix":"Initialize the router with `createRouter({ strictTrailingSlash: true })` to enable strict trailing slash behavior.","message":"By default, `radix3` ignores trailing slashes for matching and adding routes. If strict trailing slash matching is required, you must explicitly enable it.","severity":"gotcha","affected_versions":">=0.7.0"},{"fix":"Use `\\:` to match a literal colon and `\\*` to match a literal asterisk in your route definition paths.","message":"Special 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.","severity":"gotcha","affected_versions":">=0.7.12"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your import statement matches your module system. For ESM, use `import { createRouter } from 'radix3';`. For CommonJS, use `const { createRouter } = require('radix3');`.","cause":"Attempting to use CommonJS `require` syntax when the project or specific file is configured for ESM, or vice-versa.","error":"TypeError: createRouter is not a function"},{"fix":"Ensure the router is initialized with `{ strictTrailingSlash: true }` when `createRouter()` is called, and that you are using this specific router instance for lookups.","cause":"The `strictTrailingSlash` option was not correctly applied during router initialization or a new router instance was created without it.","error":"Route lookup for '/foo/' unexpectedly matches '/foo' when strictTrailingSlash is true."},{"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\\*`.","cause":"Special characters like `:` and `*` are interpreted as route parameters or wildcards by `radix3`.","error":"Unexpected route matching or no match for path containing characters like ':', '*', or '**'"}],"ecosystem":"npm"}