Orientation Arc
Routing Algorithms
Rendering and JSX
Runtime Adapters
Middleware Ecosystem
Developer Helpers
System Utilities
The following files were used as context for generating this wiki page:
Alternative Routers in Hono provide specialized mechanisms for path matching, allowing the framework to balance performance and complexity based on specific use cases. By decoupling the routing engine from the core application framework, Hono enables developers to swap matching logic for different environments or traffic patterns.
The router subsystem acts as a critical intermediary. When a request hits the Hono instance, it is transformed into a standard request object and passed to the router's match function. The router then efficiently resolves the incoming path and method against the registered routes, returning a handler set that the runtime subsequently executes.
The system supports multiple router implementations—such as RegExpRouter, TrieRouter, and LinearRouter. By using a SmartRouter (or other selection logic), Hono can choose the most performant matcher at runtime, or developers can customize the router initialization. This architecture ensures that the overhead of request dispatching remains minimal regardless of the number of routes or the complexity of path parameters.
The SmartRouter acts as a facade, coordinating between multiple underlying routing strategies. In src/preset/quick.ts, the Hono class initializes with a SmartRouter configured to use both LinearRouter and TrieRouter. This composition allows the system to leverage the strengths of different matching algorithms concurrently.
Sources: src/preset/quick.ts:13-24, src/hono.ts:16-34
The RegExpRouter is designed for high-performance route resolution by compiling paths into regular expressions. The buildMatcherFromPreprocessedRoutes function is central to this mechanism: it sorts routes, inserting them into a Trie structure to produce a highly efficient regex that performs the matching task in a single pass.
Note
The RegExpRouter pre-compiles routes into a regex matcher. The registration order and path complexity directly impact the compiled complexity.
The buildAllMatchers method acts as the lifecycle trigger for finalization. It cycles through the routes, builds the MatcherMap, and then explicitly nullifies internal structures (#middleware = #routes = undefined) to free memory and prevent further modifications.
Sources: src/router/reg-exp-router/router.ts:34-103, src/router/reg-exp-router/router.ts:208-222
The LinearRouter uses a flat array of route registrations, iterating through them linearly (#routes: [string, string, T][]). This approach is optimal for small route sets where the overhead of building a complex trie or regex would outweigh the cost of direct comparison.
The core matching algorithm resides in the match method, which uses a label-based approach for static routes and regex-based matching for parameters. It contains a ROUTES_LOOP label that acts as a control-flow break mechanism, enabling the loop to move to the next candidate immediately if the current path segment fails to match.
Sources: src/router/linear-router/router.ts:11-23, src/router/linear-router/router.ts:25-110
Both routers interact closely with src/utils/url.ts to process segments and extract parameters. The extractGroupsFromPath function performs a destructive replacement on the path to isolate segments enclosed in {}. This transformation allows the internal routing logic to treat parameter placeholders as discrete tokens during the trie insertion or regex generation phase.
Sources: src/utils/url.ts:23-33, src/utils/url.ts:171-206
The router system employs strict checks during route registration. When the trie encounters a conflict—specifically, when a path pattern cannot be resolved predictably—it throws an UnsupportedPathError.
Caution
The router assumes that the configuration passed via the constructor (e.g., options.router) is immutable after initialization. If the internal state is modified post-match, the results become non-deterministic.
Sources: src/router/reg-exp-router/router.ts:61-65
The current architecture prioritizes flexibility. The system supports swapping routers at build time, and providing multiple implementations allows Hono to optimize based on the application's unique route topology.
Sources: src/hono.ts:28-32, src/preset/quick.ts:20-22