,
]
): HonoBase<
IntersectNonAnyTypes<[E, E2, E3, E4, E5, E6, E7, E8, E9, E10]>,
S,
BasePath,
MergedPath
>
//// app.use(path, ...handlers[])
(
path: P,
...handlers: MiddlewareHandler>[]
): HonoBase>
}
```
Sources: [src/types.ts:1431-1449](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/types.ts:1431-1449)
```typescript
M5 extends H = H,
M6 extends H = H,
M7 extends H = H,
M8 extends H = H,
M9 extends H = H,
>(
method: M,
path: P,
...handlers: [
H & M1,
H & M2,
H & M3,
H & M4,
H & M5,
H & M6,
H & M7,
H & M8,
H & M9,
H,
]
): HonoBase<
IntersectNonAnyTypes<[E, E2, E3, E4, E5, E6, E7, E8, E9, E10, E11]>,
S &
ToSchema<
M,
MergePath,
I10,
| MergeTypedResponse
| MergeMiddlewareResponse
| MergeMiddlewareResponse
| MergeMiddlewareResponse
| MergeMiddlewareResponse
| MergeMiddlewareResponse
| MergeMiddlewareResponse
| MergeMiddlewareResponse
| MergeMiddlewareResponse
| MergeMiddlewareResponse
>,
BasePath,
MergePath
>
```
Sources: [src/types.ts:1901-1941](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/types.ts:1901-1941)
## Route storage and path resolution
### Internal Route Structure and Routing Tables
When handlers are registered through method shortcuts, `app.use()`, or `app.on()`, `HonoBase` invokes its private `#addRoute` method to normalize paths, uppercase method identifiers, and populate internal routing structures. Every registered route is encapsulated as a `RouterRoute` object containing the assigned `basePath`, the fully qualified `path`, the HTTP `method`, and the target `handler`.
```typescript
#addRoute(method: string, path: string, handler: H, baseRoutePath?: string): void {
method = method.toUpperCase()
path = mergePath(this._basePath, path)
const r: RouterRoute = {
basePath:
baseRoutePath !== undefined ? mergePath(this._basePath, baseRoutePath) : this._basePath,
path,
method,
handler,
}
this.router.add(method, path, [handler, r])
this.routes.push(r)
}
```
Sources: [src/hono-base.ts:385-397](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L385-L397)
The `RouterRoute` entries are dual-stored: they are pushed sequentially into the instance's public `routes` array for introspection or sub-application composition, and they are registered directly into the active `router` instance by calling `this.router.add(method, path, [handler, r])`. This associates each route pattern with a tuple containing the handler and its metadata description.
```source
src/hono-base.ts:124| routes: RouterRoute[] = []
```
Sources: [src/hono-base.ts:124](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L124)
> [!NOTE]
> The router implementation stores tuples of `[handler, r]` as values for each registered method and path combination, permitting downstream dispatch logic to access both the executable function and the complete `RouterRoute` descriptor during request matching.
### Path Normalization and Prefix Merging
Path normalization and prefix combining are handled by utility functions imported from `./utils/url`, specifically `mergePath`, `getPath`, and `getPathNoStrict`. Within `#addRoute`, incoming paths are passed through `mergePath(this._basePath, path)` to ensure that any configured application base path prefixes are correctly prepended without redundant slashes or missing separators.
```typescript
method = method.toUpperCase()
path = mergePath(this._basePath, path)
```
Sources: [src/hono-base.ts:386-387](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L386-L387)
The active `getPath` function is selected during instantiation based on the `strict` option flag. If `strict` evaluates to true (the default), `options.getPath ?? getPath` is selected, enforcing exact path matching including trailing slashes. If `strict` is set to false, `getPathNoStrict` is assigned to normalize out trailing slashes during path resolution.
```typescript
const { strict, ...optionsWithoutStrict } = options
Object.assign(this, optionsWithoutStrict)
this.getPath = (strict ?? true) ? (options.getPath ?? getPath) : getPathNoStrict
}
```
Sources: [src/hono-base.ts:170-173](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L170-L173)
> [!CAUTION]
> Modifying the `strict` flag alters how `getPath` processes incoming URLs at runtime; mixing strict and non-strict sub-applications without accounting for trailing slash normalization can lead to unexpected `404 Not Found` responses during lookup matching.
## Sub-application routing and basePath
### Scoped basePath Cloning and Instance Isolation
Modular composition in Hono relies on creating isolated sub-applications and scoping routing prefixes via `.basePath()`. The `.basePath()` method invokes a private `#clone()` helper that instantiates a new Hono instance sharing the parent's underlying `router`, `getPath`, `errorHandler`, `#notFoundHandler`, and `routes` references, while updating the private `_basePath` property through `mergePath(this._basePath, path)`.
```typescript
#clone(): Hono {
const clone = new Hono({
router: this.router,
getPath: this.getPath,
})
clone.errorHandler = this.errorHandler
clone.#notFoundHandler = this.#notFoundHandler
clone.routes = this.routes
return clone
}
```
Sources: [src/hono-base.ts:175-184](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L175-L174)
```typescript
basePath(
path: SubPath
): Hono, MergePath> {
const subApp = this.#clone()
subApp._basePath = mergePath(this._basePath, path)
return subApp
}
```
Sources: [src/hono-base.ts:247-253](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L247-L253)
> [!TIP]
> Calling `.basePath()` does not duplicate the underlying router or existing route collection; instead, it returns a lightweight shadow instance pre-configured with an extended `_basePath` value for subsequent route registrations.
### Composing Sub-Applications with route()
Sub-applications and independent Hono router instances can be merged into a parent application using the `.route()` method. When `.route(path, app)` is invoked, it creates a scoped sub-application at the specified mount path and iterates over all `app.routes` definitions, re-registering each route into the parent's router and route collection.
```typescript
route<
SubPath extends string,
SubEnv extends Env,
SubSchema extends Schema,
SubBasePath extends string,
SubCurrentPath extends string,
>(
path: SubPath,
app: Hono
): Hono> | S, BasePath, CurrentPath> {
const subApp = this.basePath(path)
app.routes.map((r) => {
let handler
if (app.errorHandler === errorHandler) {
handler = r.handler
} else {
handler = async (c: Context, next: Next) =>
(await compose([], app.errorHandler)(c, () => r.handler(c, next))).res
;(handler as any)[COMPOSED_HANDLER] = r.handler
}
subApp.#addRoute(r.method, r.path, handler, r.basePath)
})
return this
}
```
Sources: [src/hono-base.ts:208-232](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L208-L232)
If the mounted sub-application defines a custom error handler differing from the default `errorHandler`, `.route()` wraps each copied route handler in a composed execution block that routes errors through the sub-application's specific error boundary before falling back or continuing execution.
```typescript
if (app.errorHandler === errorHandler) {
handler = r.handler
} else {
handler = async (c: Context, next: Next) =>
(await compose([], app.errorHandler)(c, () => r.handler(c, next))).res
;(handler as any)[COMPOSED_HANDLER] = r.handler
}
```
Sources: [src/hono-base.ts:221-227](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L221-L227)
### External Framework Mounting with mount()
External request handlers and applications built with other frameworks can be integrated into a Hono application using the `.mount()` method. It processes optional `MountOptions` configurations, which accept either a custom `MountOptionHandler` function or an options object containing an `optionHandler` and a `replaceRequest` strategy.
```typescript
mount(
path: string,
applicationHandler: (request: Request, ...args: any) => Response | Promise,
options?: MountOptions
): Hono {
// handle options
let replaceRequest: MountReplaceRequest | undefined
let optionHandler: MountOptionHandler | undefined
if (options) {
if (typeof options === 'function') {
optionHandler = options
} else {
optionHandler = options.optionHandler
if (options.replaceRequest === false) {
replaceRequest = (request) => request
} else {
replaceRequest = options.replaceRequest
}
}
}
```
Sources: [src/hono-base.ts:328-347](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L328-L347)
The request transformation and argument extraction behavior during execution depend on whether explicit options are provided:
| Option Property | Default Behavior | Custom Behavior |
| :--- | :--- | :--- |
| `replaceRequest` | Strips the mounted path prefix from the incoming request URL pathname | Passes the request through a custom `MountReplaceRequest` function or preserves it unchanged if set to `false` |
| `optionHandler` | Passes `[c.env, executionContext]` extracted from the active `Context` | Invokes the custom `MountOptionHandler` function and normalizes its return value into an array |
```typescript
const getOptions: (c: Context) => unknown[] = optionHandler
? (c) => {
const options = optionHandler!(c)
return Array.isArray(options) ? options : [options]
}
: (c) => {
let executionContext: ExecutionContext | undefined = undefined
try {
executionContext = c.executionCtx
} catch {} // Do nothing
return [c.env, executionContext]
}
replaceRequest ||= (() => {
const mergedPath = mergePath(this._basePath, path)
const pathPrefixLength = mergedPath === '/' ? 0 : mergedPath.length
return (request) => {
const url = new URL(request.url)
url.pathname = this.getPath(request).slice(pathPrefixLength) || '/'
return new Request(url, request)
}
})()
```
Sources: [src/hono-base.ts:350-370](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L350-L370)
Once the request transformer and argument extractors are resolved, `.mount()` registers a wildcard route matching `mergePath(path, '*')` with `METHOD_NAME_ALL`, executing the external handler inside a middleware wrapper.
```typescript
const handler: MiddlewareHandler = async (c, next) => {
const res = await applicationHandler(replaceRequest(c.req.raw), ...getOptions(c))
if (res) {
return res
}
await next()
}
this.#addRoute(METHOD_NAME_ALL, mergePath(path, '*'), handler)
return this
}
```
Sources: [src/hono-base.ts:372-383](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L372-L383)
## Application-level error handling
### Default Handlers and Customization
Hono provides built-in fallback handlers for unhandled routing misses and runtime exceptions. The default `notFoundHandler` returns a plain text response with status code `404` and the body `404 Not Found`.
```typescript
const notFoundHandler: NotFoundHandler = (c) => {
return c.text('404 Not Found', 404)
}
```
Sources: [src/hono-base.ts:31-33](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L31-L33)
The default `errorHandler` inspects caught exceptions to check if they implement a `getResponse()` method. If present, it directly returns the response provided by the error instance; otherwise, it formats a generic internal error response.
```typescript
const errorHandler: ErrorHandler = (err, c) => {
if ('getResponse' in err) {
const res = err.getResponse()
return c.newResponse(res.body, res)
}
console.error(err)
return c.text('Internal Server Error', 500)
```
Sources: [src/hono-base.ts:35-41](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L35-L41)
Applications can override these default behaviors by registering custom handlers via the `.notFound()` and `.onError()` methods, which update the instance's `#notFoundHandler` and `errorHandler` properties and return the modified Hono instance.
```typescript
onError = (handler: ErrorHandler): Hono => {
this.errorHandler = handler
return this
}
/**
* `.notFound()` allows you to customize a Not Found Response.
*
* @see {@link https://hono.dev/docs/api/hono#not-found}
*
* @param {NotFoundHandler} handler - request handler for not-found
* @returns {Hono} changed Hono instance
*
* @example
* ```ts
* app.notFound((c) => {
* return c.text('Custom 404 Message', 404)
* })
* ```
*/
notFound = (handler: NotFoundHandler): Hono => {
this.#notFoundHandler = handler
return this
}
```
Sources: [src/hono-base.ts:271-294](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L271-L294)
### Exception Dispatching and Error Normalization
During request dispatching in `#dispatch()`, runtime exceptions thrown within route handlers or middleware are caught and passed to `#handleError()`. The `#handleError()` method checks if the thrown value is an instance of `Error`; if so, it delegates to the registered `errorHandler`. If the thrown value is not an `Error` instance, it rethrows the raw value.
```typescript
#handleError(err: unknown, c: Context): Response | Promise {
if (err instanceof Error) {
return this.errorHandler(err, c)
}
throw err
}
```
Sources: [src/hono-base.ts:399-404](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L399-L404)
> [!WARNING]
> Non-`Error` exceptions (such as thrown strings or primitives) bypass the custom `errorHandler` entirely and propagate out of `#handleError()`, potentially causing unhandled promise rejections if not caught at the top-level fetch boundary.
When dispatching requests with a single matching handler or via composed middleware chains, exceptions originating from synchronous code execution, asynchronous promise rejections, or unfinalized context states are intercepted and routed through the error handling pipeline.
```typescript
if (matchResult[0].length === 1) {
let res: ReturnType
try {
res = matchResult[0][0][0][0](c, async () => {
c.res = await this.#notFoundHandler(c)
})
} catch (err) {
return this.#handleError(err, c)
}
return res instanceof Promise
? res
.then(
(resolved: Response | undefined) =>
resolved || (c.finalized ? c.res : this.#notFoundHandler(c))
)
.catch((err: Error) => this.#handleError(err, c))
: (res ?? this.#notFoundHandler(c))
}
const composed = compose(matchResult[0], this.errorHandler, this.#notFoundHandler)
return (async () => {
try {
const context = await composed(c)
if (!context.finalized) {
throw new Error(
'Context is not finalized. Did you forget to return a Response object or `await next()`?'
)
}
return context.res
} catch (err) {
return this.#handleError(err, c)
}
})()
}
```
Sources: [src/hono-base.ts:430-466](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L430-L466)
## Fetch interface and runtime execution
### Standard Fetch Handler and Request Dispatching
The `.fetch()` method serves as the primary entry point for Hono applications, adhering to the standard Web Fetch API signature by accepting a `Request` object, optional environment bindings, and an `ExecutionContext`. It delegates directly to the private `#dispatch()` method using `request.method` and the provided bindings.
```typescript
fetch: (
request: Request,
Env?: E['Bindings'] | {},
executionCtx?: ExecutionContext
) => Response | Promise = (request, ...rest) => {
return this.#dispatch(request, rest[1], rest[0], request.method)
}
```
Sources: [src/hono-base.ts:479-485](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L479-L485)
Inside `#dispatch()`, HTTP `HEAD` requests are intercepted and handled specially by delegating to a `GET` dispatch and stripping the response body, returning a new `Response` with a `null` body.
```typescript
if (method === 'HEAD') {
return (async () =>
new Response(null, await this.#dispatch(request, executionCtx, env, 'GET')))()
}
```
Sources: [src/hono-base.ts:413-416](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L413-L416)
For all other methods, path resolution is performed via the configured `getPath` helper, and the router matches the method against the path to produce a `matchResult`. A new `Context` instance is then instantiated with the request, matched route handlers, bindings, and execution context.
```typescript
const path = this.getPath(request, { env })
const matchResult = this.router.match(method, path)
const c = new Context(request, {
path,
matchResult,
env,
executionCtx,
notFoundHandler: this.#notFoundHandler,
})
```
Sources: [src/hono-base.ts:418-427](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L418-L427)
> [!NOTE]
> If a match yields exactly one handler, Hono bypasses the full `[[Middleware Composition|compose]]` pipeline overhead to execute the handler directly, falling back to the not-found handler if unfinalized.
```typescript
// Do not `compose` if it has only one handler
if (matchResult[0].length === 1) {
let res: ReturnType
try {
res = matchResult[0][0][0][0](c, async () => {
c.res = await this.#notFoundHandler(c)
})
} catch (err) {
return this.#handleError(err, c)
}
return res instanceof Promise
? res
.then(
(resolved: Response | undefined) =>
resolved || (c.finalized ? c.res : this.#notFoundHandler(c))
)
.catch((err: Error) => this.#handleError(err, c))
: (res ?? this.#notFoundHandler(c))
}
```
Sources: [src/hono-base.ts:429-448](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L429-L448)
When multiple handlers match, `#dispatch()` invokes `compose` with the matched handlers, error handler, and not-found handler, ensuring that context finalization invariants are strictly enforced on the resulting execution pipeline.
```typescript
const composed = compose(matchResult[0], this.errorHandler, this.#notFoundHandler)
return (async () => {
try {
const context = await composed(c)
if (!context.finalized) {
throw new Error(
'Context is not finalized. Did you forget to return a Response object or `await next()`?'
)
}
return context.res
} catch (err) {
return this.#handleError(err, c)
}
})()
}
```
Sources: [src/hono-base.ts:450-466](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L450-L466)
### Testing Helpers and Service Worker Integration
Hono provides the `.request()` method as a utility primarily designed for testing. It accepts `Request`, string, or `URL` inputs along with optional request initialization options, environment bindings, and execution context, automatically resolving relative paths against a localhost base if necessary.
```typescript
request = (
input: Request | string | URL,
requestInit?: RequestInit,
Env?: E['Bindings'] | {},
executionCtx?: ExecutionContext
): Response | Promise => {
if (input instanceof Request) {
return this.fetch(requestInit ? new Request(input, requestInit) : input, Env, executionCtx)
}
input = input.toString()
return this.fetch(
new Request(
/^https?:\/\//.test(input) ? input : `http://localhost${mergePath('/', input)}`,
requestInit
),
Env,
executionCtx
)
}
```
Sources: [src/hono-base.ts:499-517](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L499-L517)
For environments adhering to the Service Worker API (such as non-ES module Cloudflare Workers), the `.fire()` method registers a global `fetch` event listener via `addEventListener`, responding to incoming fetch events by invoking `#dispatch()`.
```typescript
fire = (): void => {
// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore
addEventListener('fetch', (event: FetchEventLike): void => {
event.respondWith(this.#dispatch(event.request, event, undefined, event.request.method))
})
}
```
Sources: [src/hono-base.ts:536-542](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L536-L542)
> [!WARNING]
> The `.fire()` method is deprecated and should be avoided in modern ES module runtimes; use `fire` from `hono/service-worker` instead.
```typescript
* @deprecated
* Use `fire` from `hono/service-worker` instead.
```
Sources: [src/hono-base.ts:522-523](https://github.com/blade47/hono/blob/e50df01453e71b071c3e6136b161b160b9fdf916/src/hono-base.ts#L522-L523)
## Related
- [Request Lifecycle](https://www.doc0.dev/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/core-engine/request-lifecycle)
- [Execution Context](https://www.doc0.dev/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/core-engine/execution-context)
- [Router Contracts](https://www.doc0.dev/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/routing/router-contracts)
## Sitemap
See the full [sitemap](https://www.doc0.dev/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/llms.txt) for all pages in this wiki.