---
title: "Alternative Routers"
description: "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 eng..."
last_updated: "2026-07-02T09:13:46.849517+00:00"
canonical_url: "https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/routing-algorithms/alternative-routers"
---

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [package.json](https://github.com/blade47/hono/blob/main/package.json)
- [src/types.ts](https://github.com/blade47/hono/blob/main/src/types.ts)
- [src/preset/quick.ts](https://github.com/blade47/hono/blob/main/src/preset/quick.ts)
- [src/adapter/aws-lambda/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts)
- [src/hono.ts](https://github.com/blade47/hono/blob/main/src/hono.ts)
- [src/utils/url.ts](https://github.com/blade47/hono/blob/main/src/utils/url.ts)
- [src/router/reg-exp-router/router.ts](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/router.ts)
- [src/router/linear-router/router.ts](https://github.com/blade47/hono/blob/main/src/router/linear-router/router.ts)
</details>

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.

## Smart Router Orchestration
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.

```mermaid
classDiagram
    class Hono {
        +router: SmartRouter
    }
    class SmartRouter {
        -routers: Router[]
        +match(method, path)
    }
    class TrieRouter {
        +match(method, path)
    }
    class LinearRouter {
        +match(method, path)
    }
    Hono *-- SmartRouter
    SmartRouter o-- TrieRouter
    SmartRouter o-- LinearRouter
```
Sources: [src/preset/quick.ts:13-24](https://github.com/blade47/hono/blob/main/src/preset/quick.ts#L13-L24), [src/hono.ts:16-34](https://github.com/blade47/hono/blob/main/src/hono.ts#L16-L34)

## RegExpRouter Implementation
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](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/router.ts#L34-L103), [src/router/reg-exp-router/router.ts:208-222](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/router.ts#L208-L222)

## LinearRouter Matching Logic
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](https://github.com/blade47/hono/blob/main/src/router/linear-router/router.ts#L11-L23), [src/router/linear-router/router.ts:25-110](https://github.com/blade47/hono/blob/main/src/router/linear-router/router.ts#L25-L110)

## Path Parameter Extraction
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.

| Function | Responsibility |
| :--- | :--- |
| `splitPath` | Tokenizes paths by `/` and removes empty segments. |
| `getPattern` | Returns a `Pattern` tuple for route segments (wildcards or regexes). |
| `checkOptionalParameter` | Resolves routes with optional segments (e.g., `:id?`) into flattened variants. |

Sources: [src/utils/url.ts:23-33](https://github.com/blade47/hono/blob/main/src/utils/url.ts#L23-L33), [src/utils/url.ts:171-206](https://github.com/blade47/hono/blob/main/src/utils/url.ts#L171-L206)

## Error Handling and Invariants
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](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/router.ts#L61-L65)

## Design Trade-offs
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.

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| `RegExpRouter` compilation | Fast execution for large route sets. | High initial startup cost. |
| `LinearRouter` array | Memory efficient and fast for small sets. | O(N) lookup time. |
| `SmartRouter` facade | Easy runtime switching between matchers. | Slightly increased abstraction layer overhead. |

Sources: [src/hono.ts:28-32](https://github.com/blade47/hono/blob/main/src/hono.ts#L28-L32), [src/preset/quick.ts:20-22](https://github.com/blade47/hono/blob/main/src/preset/quick.ts#L20-L22)

## Related

- [RegExp Router](https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/routing-algorithms/regexp-router)
- [Smart Router](https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/routing-algorithms/smart-router)


## Sitemap

See the full [sitemap](https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/llms.txt) for all pages in this wiki.