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:
Application Routing is the foundational subsystem in Hono responsible for mapping incoming HTTP requests to their corresponding handler functions. It acts as the central traffic controller, enabling developers to build complex API surfaces by registering middleware and route handlers to specific URL paths and HTTP methods.
The system is designed with a pluggable router architecture, allowing the application instance to remain agnostic of the specific matching strategy. By decoupling the registration API from the execution engine, Hono achieves both high performance and modularity, supporting different router implementations that prioritize either raw speed or advanced pattern matching.
During the lifecycle of a request, the routing subsystem translates an incoming URL into a result provided by the router implementation. This result contains the ordered list of handlers (middleware and route handlers) that should execute for the given request. This dispatch mechanism ensures that global middleware, path-specific middleware, and final route handlers are executed in the correct sequence, respecting the order of registration.
Hono employs a strategy-based routing approach. The main Hono class inherits from a base class that operates on a generic Router interface, while specific implementations are provided at instantiation.
The SmartRouter acts as a high-level router that can aggregate multiple specialized routers. For example, the standard Hono implementation uses a SmartRouter that orchestrates both RegExpRouter and TrieRouter to balance performance across different path complexity levels.
Sources: src/hono-base.ts:10-11, 118, src/hono.ts:3-5, 30
When a user calls app.get(), app.post(), or similar methods, the routing subsystem performs a multi-step registration process via private methods within the base class.
_basePath.RouterRoute object is instantiated, capturing the method, path, and handler reference.router.add() method for indexing.this.routes) for later retrieval.Sources: src/hono-base.ts:124, 134, 385-396
When a request arrives at the fetch() method, the subsystem executes the dispatch logic. This is the critical "hot path" where the router is queried.
getPath function (which can be customized) isolates the pathname.match(method, path) method returns an ordered array of handlers.Context object is initialized with the route matches.compose function wraps all handlers (both middleware and the final route handler) into a single, chained execution pipeline.Important
The composition step is skipped if only one handler is matched, an optimization that avoids the overhead of creating an execution chain for trivial routes.
Sources: src/hono-base.ts:419-427, 430
When multiple patterns could potentially match a single incoming request (e.g., wildcards vs. exact paths), the RegExpRouter handles the selection process:
staticMap first for O(1) lookup.RegExpRouter, routes are sorted by path length and static status; if paths have equal specificity, the order of registration determines the match priority (the first registered route wins).Sources: src/router/reg-exp-router/router.ts:47-49, 62
The routing subsystem exposes tools to inspect the active route during the execution of a handler. These helpers are defined in src/helper/route/index.ts.
The following example demonstrates how to define an application, apply middleware, and use a sub-router for route grouping.
import { Hono } from 'hono'
const app = new Hono()
const subApp = new Hono()
// Middleware applied to all routes
app.use('*', async (c, next) => {
console.log('Request received')
await next()
})
// Sub-app grouping
subApp.get('/posts', (c) => c.text('List of posts'))
app.route('/api', subApp) // Path becomes /api/posts
// Direct route definition
app.get('/hello/:name', (c) => {
const name = c.req.param('name')
return c.text(`Hello ${name}`)
})
// Dispatching for testing
const response = await app.request('/api/posts')Sources: src/hono-base.ts:157, 191, 208