# blade47/hono Wiki

## Overview

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/overview

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

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

- [src/context.ts](https://github.com/blade47/hono/blob/main/src/context.ts)
- [src/types.ts](https://github.com/blade47/hono/blob/main/src/types.ts)
- [src/hono-base.ts](https://github.com/blade47/hono/blob/main/src/hono-base.ts)
- [src/adapter/aws-lambda/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts)
- [src/adapter/cloudflare-pages/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/handler.ts)
- [src/hono.ts](https://github.com/blade47/hono/blob/main/src/hono.ts)
- [src/preset/quick.ts](https://github.com/blade47/hono/blob/main/src/preset/quick.ts)
- [src/adapter/lambda-edge/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/lambda-edge/handler.ts)
</details>

Hono is a high-performance, lightweight web framework designed for edge-native environments, though it maintains compatibility across standard Node.js and serverless environments. Its architecture is built around the `Hono` class (aliased as `HonoBase` within its own module), which provides a router-agnostic foundation for defining routes, middleware, and request-handling pipelines. This design separation allows Hono to be modular: the framework core is decoupled from the router implementation and the runtime-specific adapter.

The system centers on the `Context` object, which provides an abstraction over the native `Request` and `Response` objects. By wrapping these in a specialized container, Hono enables efficient propagation of environment variables, request state, and execution context. This architecture resolves the primary problem of fragmented web standard support in different cloud runtimes by providing a unified, TypeScript-first API that behaves consistently whether running on Cloudflare Workers, AWS Lambda, or local environments.

The framework's operation is structured into a pipeline: a request enters via an adapter's `handle` or `fetch` method, is routed using a pluggable `Router` (e.g., `SmartRouter`, `RegExpRouter`), and is executed through a sequence of middleware and handlers orchestrated by a composition engine. By avoiding heavy dependencies and prioritizing a clean, composable design, Hono provides a "build-to-fit" experience for high-traffic, low-latency applications.

## Core Framework Architecture
The framework is managed via the `Hono` class, which manages route registration, error handling, and the lifecycle of the incoming HTTP request. Unlike typical frameworks, this class does not contain a hardcoded router; it is an implementation that relies on an injected `Router` instance provided at initialization or via specific class extensions.

When a request is received, `fetch()` serves as the primary entry point, performing the following:
1. Resolves the path using the configured `getPath` function (defaulting to a standard URL parser).
2. Executes a route match against the `router` property, which returns a `matchResult` containing candidate handlers.
3. Instantiates a `Context` object that holds the `Request`, `env` (bindings), and `matchResult`.
4. If multiple handlers are present, it uses a `compose` function to execute them sequentially, passing `c` (Context) and `next()` through the pipeline.

Sources: [src/hono-base.ts:98-124](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L98-L124), [src/hono-base.ts:479-485](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L479-L485)

## Context Abstraction
The `Context` class is the primary interface for handlers to interact with an incoming request and craft a response. It encapsulates the underlying `Request` object and offers a typed API for setting response headers, JSON bodies, or HTML.

Internal state tracking includes the `finalized` boolean. When a handler completes its logic, setting a response via `res` or other helper methods often triggers a transition to `finalized = true`. This state invariant prevents further modification to the response once it is in the process of being committed to the network, ensuring the integrity of the response lifecycle.

> [!TIP]
> Use `c.set()` and `c.get()` to pass data between middleware. These variables are managed internally by a `Map` instance within the `Context` and are scoped strictly to the current request lifecycle.

Sources: [src/context.ts:293-301](https://github.com/blade47/hono/blob/main/src/context.ts#L293-L301), [src/context.ts:317-317](https://github.com/blade47/hono/blob/main/src/context.ts#L317-L317), [src/context.ts:546-556](https://github.com/blade47/hono/blob/main/src/context.ts#L546-L556)

## Request Routing and Dispatch
Hono utilizes a pluggable routing mechanism. The constructor allows injecting different routers through the `options.router` field. The `SmartRouter` (used by default) acts as an aggregator, choosing the most efficient router implementation based on the registration of routes.

The flow for adding a route involves:
1. Identifying the method and path (merged with the current `basePath`).
2. The router's `add()` method is invoked, storing the handler and route metadata.

When dispatching, Hono matches the request URL path to the stored route. If multiple routes overlap, the specific order of matching is determined by the `Router`'s internal implementation.

```mermaid
flowchart TD
    A[Request] --> B{Router.match}
    B -->|Found| C[Create Context]
    C --> D[Compose Middleware]
    D --> E[Handler Execution]
    E --> F[Finalized Response]
```
Sources: [src/hono-base.ts:385-397](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L385-L397), [src/hono-base.ts:419-427](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L419-L427), [src/hono.ts:26-33](https://github.com/blade47/hono/blob/main/src/hono.ts#L26-L33)

## Adapter Mechanism
Hono is platform-agnostic, achieving this via adapters found in `src/adapter/`. These adapters translate platform-specific request objects (e.g., AWS Lambda's events or Cloudflare's `EventContext`) into a standard `Request` object that Hono's `.fetch()` can process.

The `aws-lambda` adapter uses specialized processor logic (such as `ALBProcessor` or `EventV1Processor`). Each processor implements a standard interface for extracting the method, path, and headers, allowing Hono to handle different AWS trigger types uniformly.

| Adapter | Responsibility | Primary Data Mapping |
| :--- | :--- | :--- |
| `aws-lambda` | Event translation | Maps event headers/body to `Headers` and `Request`. |
| `cloudflare-pages` | Middleware orchestration | Injects `EventContext` into the Hono environment. |
| `lambda-edge` | CloudFront event mapping | Converts CloudFront event structure to `Headers`. |

Sources: [src/adapter/aws-lambda/handler.ts:278-317](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L278-L317), [src/adapter/cloudflare-pages/handler.ts:32-46](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/handler.ts#L32-L46)

## Error Handling
Hono implements a catch-all mechanism for runtime exceptions. The default `errorHandler` is defined in `HonoBase` to provide a fallback: it logs the error to the console and returns a generic "Internal Server Error" (500) response.

Custom error handlers can be registered via the instance's `onError` property or method assignment. If a handler throws an `HTTPException` (which carries an embedded response), the framework unwraps and returns that response directly rather than defaulting to 500.

> [!WARNING]
> Always return a Response from your error handler. If the error handler throws an exception, the framework execution will bubble that error to the underlying runtime adapter, likely resulting in a non-HTTP compliant failure.

Sources: [src/hono-base.ts:35-42](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L35-L42), [src/hono-base.ts:271-274](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L271-L274)

## Worked Example: Defining a Route
The following code demonstrates defining a simple JSON endpoint exercising the Hono lifecycle.

```typescript
import { Hono } from 'hono';

const app = new Hono();

// Route registration
app.get('/api/message', (c) => {
  // Set custom header
  c.header('X-Hono-Custom', 'Value');
  // Return JSON response
  return c.json({ message: 'Hello, world!' });
});
```
Sources: [src/hono.ts:16-34](https://github.com/blade47/hono/blob/main/src/hono.ts#L16-L34), [src/context.ts:708-721](https://github.com/blade47/hono/blob/main/src/context.ts#L708-L721)

## Design Trade-offs

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| Router-agnostic core | Flexibility to swap routers and adapters. | Slightly higher complexity for framework developers. |
| `Context` encapsulation | Consistent API across disparate runtimes. | Minor allocation overhead for every request. |
| Middleware composition | Simple, linear control flow of `next()`. | Recursion depth limits in extremely long pipelines. |

Sources: [src/hono-base.ts:98-103](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L98-L103), [src/context.ts:293-299](https://github.com/blade47/hono/blob/main/src/context.ts#L293-L299), [src/compose.ts](https://github.com/blade47/hono/blob/main/src/compose.ts)

## Related

- [[Quick Start]]
- [[Project Structure]]
- [[Application Routing]]


---

## Quick Start

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/quick-start

<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/hono-base.ts](https://github.com/blade47/hono/blob/main/src/hono-base.ts)
- [src/context.ts](https://github.com/blade47/hono/blob/main/src/context.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/adapter/cloudflare-pages/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/handler.ts)
- [src/adapter/lambda-edge/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/lambda-edge/handler.ts)
- [src/helper/proxy/index.ts](https://github.com/blade47/hono/blob/main/src/helper/proxy/index.ts)
- [src/preset/tiny.ts](https://github.com/blade47/hono/blob/main/src/preset/tiny.ts)
- [src/index.ts](https://github.com/blade47/hono/blob/main/src/index.ts)
- [runtime-tests/workerd/index.ts](https://github.com/blade47/hono/blob/main/runtime-tests/workerd/index.ts)
- [src/adapter/vercel/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/vercel/handler.ts)
- [src/adapter/netlify/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/netlify/handler.ts)
- [src/helper/dev/index.ts](https://github.com/blade47/hono/blob/main/src/helper/dev/index.ts)
- [src/router/linear-router/index.ts](https://github.com/blade47/hono/blob/main/src/router/linear-router/index.ts)
- [src/adapter/cloudflare-pages/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/index.ts)
- [src/adapter/vercel/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/vercel/index.ts)
- [src/adapter/service-worker/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/service-worker/index.ts)
- [src/router/smart-router/index.ts](https://github.com/blade47/hono/blob/main/src/router/smart-router/index.ts)
- [src/adapter/deno/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/deno/index.ts)
- [src/adapter/cloudflare-workers/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-workers/index.ts)
- [jsr.json](https://github.com/blade47/hono/blob/main/jsr.json)
- [src/adapter/aws-lambda/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/index.ts)
- [src/adapter/lambda-edge/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/lambda-edge/index.ts)
- [src/router/pattern-router/index.ts](https://github.com/blade47/hono/blob/main/src/router/pattern-router/index.ts)
- [src/helper/testing/index.ts](https://github.com/blade47/hono/blob/main/src/helper/testing/index.ts)
- [src/adapter/service-worker/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/service-worker/handler.ts)
- [src/adapter/bun/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/bun/index.ts)
- [src/adapter/netlify/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/netlify/index.ts)
</details>

Hono is a web framework built fundamentally on Web Standards, designed for environments like Cloudflare Workers, Deno, Bun, and traditional Node.js/Lambda runtimes. The "Quick Start" capabilities reflect the framework's core design philosophy: to provide a lightweight, high-performance router and execution context that remains agnostic to the underlying platform.

The system achieves this by decoupling the core router implementation from the request handling logic. The `Hono` class provides the common interface for routing and middleware, while different presets allow developers to trade off binary size against routing complexity.

When starting a project, a developer interacts with the `Hono` instance, which serves as the entry point. The framework maps HTTP methods to internal route tables and provides a standardized `Context` object that encapsulates the environment, request, and lifecycle methods, ensuring that code remains portable across disparate edge and serverless providers.

## Core Initialization Mechanics

At the heart of the system, initialization occurs by constructing an `Hono` instance. The constructor accepts an optional configuration object, which allows for defining the routing strategy, strict path matching, and path normalization logic.

```typescript
// Example: Standard Quick Start initialization
import { Hono } from 'hono'
const app = new Hono()

app.get('/', (c) => c.text('Hono!'))

export default app
```
Sources: [src/index.ts:6-14](https://github.com/blade47/hono/blob/main/src/index.ts#L6-L14)

The constructor delegates to the `Hono` class, which handles the registration of HTTP methods (GET, POST, etc.) into an internal routing table using internal registration methods that populate the router.

> [!NOTE]
> The `Hono` class is the primary interface. It initializes with a default router (e.g., `SmartRouter`), while specific preset files inject different routing implementations to optimize for performance or bundle size.

Sources: [src/hono.ts:26-34](https://github.com/blade47/hono/blob/main/src/hono.ts#L26-L34), [src/preset/tiny.ts:16-20](https://github.com/blade47/hono/blob/main/src/preset/tiny.ts#L16-L20)

## Routing Architecture

Routing is the core mechanism that determines how an incoming `Request` object maps to a `Handler`. Hono utilizes a routing system based on registered patterns.

| Router Type | Implementation File | Strategy |
| :--- | :--- | :--- |
| `SmartRouter` | `src/router/smart-router/` | Adaptive; delegates to other routers based on pattern complexity. |
| `RegExpRouter` | `src/router/reg-exp-router/` | Uses regular expressions for matching dynamic paths. |
| `TrieRouter` | `src/router/trie-router/` | Uses a trie data structure for performant prefix matching. |
| `PatternRouter` | `src/router/pattern-router/` | Optimized for small, simple route definitions. |
| `LinearRouter` | `src/router/linear-router/` | Simple linear search; efficient for very few routes. |

Sources: [src/hono.ts:3-5](https://github.com/blade47/hono/blob/main/src/hono.ts#L3-L5), [src/preset/quick.ts:8-10](https://github.com/blade47/hono/blob/main/src/preset/quick.ts#L8-L10)

The routing mechanism is triggered when a request is dispatched, which takes a request and environment variables, retrieves the path, and performs a lookup to match the method and path against the internal router's index.

Sources: [src/hono-base.ts:418-419](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L418-L419)

## The Request Dispatch Flow

When a request arrives, the `fetch` method serves as the entry point. The following chain shows how the request is processed:

1. `fetch()` → Entry point; receives the raw `Request` and environment objects.
2. `dispatch` logic → Prepares the `Context` and performs route matching.
3. `router.match()` → Performs lookups to find eligible handlers.
4. `compose()` → Executes the middleware and handler stack if more than one handler is registered.

If a single handler is found, the dispatch path avoids `compose` to optimize performance, calling the handler directly and resolving its promise.

```mermaid
flowchart TD
    A[fetch] --> B["dispatch logic"]
    B --> C["router.match"]
    C --> D{Single<br>Handler?}
    D -- Yes --> E["Direct Execute"]
    D -- No --> F["compose(handlers)"]
    E --> G[Context Finalized]
    F --> G
```
Sources: [src/hono-base.ts:429-450](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L429-L450)

## The Context Object (`Context<E>`)

The `Context` object is a load-bearing structure. It is created per-request and provides the interface through which developers interact with the request data and define the response.

Key components of `Context`:
- `env`: The environment-specific bindings (e.g., KV, D1, or environment variables).
- `req`: A wrapper around the native `Request` providing helper methods.
- `res`: The response container. When set, it marks the context as `finalized`.
- `set()` / `get()`: A shared storage mechanism for variables across middleware layers.

> [!IMPORTANT]
> The `Context` object handles the logic of finalizing the response. If the `finalized` flag is false after the middleware stack completes, the framework throws an error to ensure that the developer has provided a valid response object.

Sources: [src/context.ts:300-345](https://github.com/blade47/hono/blob/main/src/context.ts#L300-L345), [src/hono-base.ts:455-459](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L455-L459)

## Adapter Logic

Hono is built to run everywhere. The adapter pattern bridges the gap between different cloud runtime event structures (like AWS API Gateway, Cloudflare Pages, or Vercel functions) and the internal `Hono.fetch` method.

| Adapter | Primary Entry Point | Strategy |
| :--- | :--- | :--- |
| `aws-lambda` | `handle()` | Converts Lambda event structures (APIGateway, ALB) to Request. |
| `cloudflare-pages` | `handle()` | Maps `EventContext` properties to the `hono` lifecycle. |
| `lambda-edge` | `handle()` | Translates `CloudFrontRequest` for CloudFront edge events. |
| `bun` | `getBunServer()` | Native integration for Bun's HTTP server. |

Sources: [src/adapter/aws-lambda/handler.ts:239-252](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L239-L252), [src/adapter/cloudflare-pages/handler.ts:32-46](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/handler.ts#L32-L46)

Each adapter implements its own handling logic. For instance, the `aws-lambda` adapter includes logic for determining if a response should be base64-encoded, which is a common requirement in API Gateway event handling.

## Development and Testing

The system includes robust helpers for development and testing. `showRoutes` provides an observability tool to inspect the route table, while `testClient` allows developers to test their applications without performing network-level I/O.

```typescript
// Example: Testing with testClient
import { Hono } from 'hono'
import { testClient } from 'hono/testing'

const app = new Hono()
app.get('/test', (c) => c.json({ data: 'ok' }))

const client = testClient(app)
const res = await client.test.$get()
const data = await res.json() // { data: 'ok' }
```
Sources: [src/helper/testing/index.ts:16-27](https://github.com/blade47/hono/blob/main/src/helper/testing/index.ts#L16-L27)

`testClient` works by injecting a custom `fetch` function that points directly to the `app.request` internal method, bypassing the need for an actual server.

Sources: [src/helper/testing/index.ts:22-24](https://github.com/blade47/hono/blob/main/src/helper/testing/index.ts#L22-L24)

## Related

- [[Overview]]
- [[Project Structure]]


---

## Project Structure

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/project-structure

<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)
- [jsr.json](https://github.com/blade47/hono/blob/main/jsr.json)
- [src/adapter/cloudflare-pages/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/handler.ts)
- [src/jsx/hooks/index.ts](https://github.com/blade47/hono/blob/main/src/jsx/hooks/index.ts)
- [src/jsx/base.ts](https://github.com/blade47/hono/blob/main/src/jsx/base.ts)
- [src/jsx/context.ts](https://github.com/blade47/hono/blob/main/src/jsx/context.ts)
- [src/middleware/jsx-renderer/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/jsx-renderer/index.ts)
- [src/helper/ssg/ssg.ts](https://github.com/blade47/hono/blob/main/src/helper/ssg/ssg.ts)
- [src/jsx/jsx-runtime.ts](https://github.com/blade47/hono/blob/main/src/jsx/jsx-runtime.ts)
- [src/jsx/index.ts](https://github.com/blade47/hono/blob/main/src/jsx/index.ts)
- [vitest.config.ts](https://github.com/blade47/hono/blob/main/vitest.config.ts)
- [src/middleware/language/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/language/index.ts)
- [src/adapter/cloudflare-pages/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/index.ts)
- [src/router.ts](https://github.com/blade47/hono/blob/main/src/router.ts)
- [src/helper/factory/index.ts](https://github.com/blade47/hono/blob/main/src/helper/factory/index.ts)
- [src/middleware/jwt/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/jwt/index.ts)
- [src/adapter/netlify/mod.ts](https://github.com/blade47/hono/blob/main/src/adapter/netlify/mod.ts)
- [src/helper/ssg/index.ts](https://github.com/blade47/hono/blob/main/src/helper/ssg/index.ts)
- [src/adapter/netlify/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/netlify/index.ts)
- [src/jsx/dom/index.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/index.ts)
- [src/types.ts](https://github.com/blade47/hono/blob/main/src/types.ts)
</details>

Hono is architected as a lightweight, modular web framework that prioritizes web standards. The project structure is carefully designed to facilitate multi-platform compatibility, including runtimes like Node.js, Bun, Deno, Cloudflare Workers, and serverless environments. By keeping the core logic decoupled from environment-specific APIs, Hono ensures consistent behavior across these diverse deployment targets while remaining highly performant.

The hierarchy is organized into specific domain folders: `src/` serves as the primary root containing the core logic, which is further sub-divided into functional subsystems like `jsx/` for templating, `middleware/` for request/response processing, `helper/` for utility operations, and `adapter/` for platform-specific glue code. This modularity allows for tree-shaking and efficient code distribution, enabling users to import only the components they require.

This wiki details the internal structure and organization of these components, tracing how Hono wires together its routing engine, rendering pipeline, and middleware chains to deliver a unified interface across different environments.

## Core Package Configuration
The project is configured via `package.json` and `jsr.json`. These files define the external API surface area, controlling how the library is exported to consumers. By utilizing granular `exports` fields, the framework allows developers to import specific sub-packages (e.g., `hono/jsx`, `hono/jwt`, `hono/adapter/cloudflare-pages`), reducing the bundle size significantly.

| Configuration File | Primary Purpose |
| :--- | :--- |
| `package.json` | Project metadata, build scripts, and ESM/CJS exports mapping. |
| `jsr.json` | Configuration for JSR registry, defining public modules and export paths. |

Sources: [package.json:1-701](https://github.com/blade47/hono/blob/main/package.json#L1-L701), [jsr.json:1-111](https://github.com/blade47/hono/blob/main/jsr.json#L1-L111)

## Adapter Architecture
Adapters act as the translation layer between Hono's `fetch`-compliant core and the native request/response objects provided by specific platforms. Each adapter lives in `src/adapter/` and provides a standard interface (typically a `handle` function) that transforms platform-specific events into a standard `Request` object.

> [!NOTE]
> The Cloudflare Pages adapter provides both a standard `handle` for worker-style routing and a `handleMiddleware` wrapper to allow Hono middleware to interact with `EventContext` bindings directly.

Sources: [src/adapter/cloudflare-pages/handler.ts:32-46](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/handler.ts#L32-L46), [src/adapter/cloudflare-pages/handler.ts:49-102](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/handler.ts#L49-L102)

## JSX Rendering Pipeline
The JSX subsystem (`src/jsx/`) is a comprehensive template rendering engine supporting both static string generation and DOM-based client-side rendering. It includes intrinsic element support, context management, and hooks (`src/jsx/hooks/index.ts`).

Hooks such as `useState` manage component-local state by maintaining a persistent hook index tracked during the rendering cycle within the context stack. This ensures that state is scoped to the specific component instance during the node tree build process.

Sources: [src/jsx/hooks/index.ts:182-243](https://github.com/blade47/hono/blob/main/src/jsx/hooks/index.ts#L182-L243)

## Routing Engine
Routing in Hono is handled by a dispatchable router interface. The `src/router.ts` defines the contract for routers. The system supports multiple router strategies (RegExp, Trie, Linear, Pattern) to allow for performance tuning depending on the complexity of the route configuration.

The dispatcher returns an array of handler-parameter mappings, which are interpreted by the core `Hono` engine to resolve execution flow based on the method and path provided by the incoming `Request`.

Sources: [src/router.ts:25-52](https://github.com/blade47/hono/blob/main/src/router.ts#L25-L52)

## Middleware and Factory Patterns
Hono uses a factory-based approach to middleware initialization. The `src/helper/factory/` module provides a way to define middleware and handlers with strict type-safety, which is crucial given the complex intersection types generated by Hono's route builder.

```mermaid
flowchart TD
    App[Hono Application] --> Factory[Factory Helper]
    Factory --> MW[Middleware Logic]
    Factory --> Hndlr[Handlers]
    MW --> Context[Context Propagation]
```
Sources: [src/helper/factory/index.ts:332-366](https://github.com/blade47/hono/blob/main/src/helper/factory/index.ts#L332-L366)

## Static Site Generation (SSG) Mechanism
The SSG helper in `src/helper/ssg/` provides a programmatic interface to crawl the Hono app and generate static files. The process involves a `pool` of concurrent requests that hit the app's `fetch` method, collecting the response content and determining the output path based on the MIME type.

The resolution of the output file extension is governed by `determineExtension`:
1. Check against the user-provided mapping (provided via `options.extensionMap`).
2. Fallback to `getExtension` (via `src/utils/mime`).
3. Default to `.html` if no MIME match is found.

Sources: [src/helper/ssg/ssg.ts:99-108](https://github.com/blade47/hono/blob/main/src/helper/ssg/ssg.ts#L99-L108)

## Design Trade-offs
The current codebase reflects several deliberate architectural choices:

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| Middleware-on-Request | High flexibility and request-lifecycle control | Complex type-level definitions |
| Adapter-based Core | Ubiquitous runtime compatibility | Increased maintenance surface for platform-specific edge cases |
| Factory Helpers | Strong type inference in handlers | Verbose boilerplate in setup |

Sources: [src/helper/factory/index.ts:332-366](https://github.com/blade47/hono/blob/main/src/helper/factory/index.ts#L332-L366), [src/adapter/cloudflare-pages/handler.ts:32-46](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/handler.ts#L32-L46)

## Related

- [[Overview]]
- [[Quick Start]]


---

## Application Routing

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/application-routing

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

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

- [src/types.ts](https://github.com/blade47/hono/blob/main/src/types.ts)
- [src/hono-base.ts](https://github.com/blade47/hono/blob/main/src/hono-base.ts)
- [src/hono.ts](https://github.com/blade47/hono/blob/main/src/hono.ts)
- [src/adapter/aws-lambda/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts)
- [src/preset/quick.ts](https://github.com/blade47/hono/blob/main/src/preset/quick.ts)
- [src/adapter/cloudflare-pages/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/handler.ts)
- [src/helper/route/index.ts](https://github.com/blade47/hono/blob/main/src/helper/route/index.ts)
- [src/request.ts](https://github.com/blade47/hono/blob/main/src/request.ts)
- [src/router/reg-exp-router/router.ts](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/router.ts)
</details>

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.

## Pluggable Router Architecture

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.

```mermaid
classDiagram
    class Router {
        <<interface>>
        add(method, path, handler)
        match(method, path)
    }
    class HonoBase {
        router: Router
        #addRoute()
        #dispatch()
    }
    class SmartRouter {
        routers: Router[]
    }
    Router <|.. SmartRouter
    HonoBase o-- Router
```
Sources: [src/hono-base.ts:10-11, 118](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L10-L11#L118), [src/hono.ts:3-5, 30](https://github.com/blade47/hono/blob/main/src/hono.ts#L3-L5#L30)

## Route Registration Flow

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.

1. **Normalization**: The path is merged with any current `_basePath`.
2. **Data Structure Creation**: A `RouterRoute` object is instantiated, capturing the method, path, and handler reference.
3. **Router Insertion**: The handler and metadata are passed to the `router.add()` method for indexing.
4. **Internal Tracking**: The route is stored in an internal array (`this.routes`) for later retrieval.

```mermaid
flowchart TD
    A["app.get(path, handler)"] --> B["HonoBase.#addRoute()"]
    B --> C["mergePath(this._basePath, path)"]
    C --> D["Create RouterRoute object"]
    D --> E["router.add()"]
    D --> F["this.routes.push(r)"]
```
Sources: [src/hono-base.ts:124, 134, 385-396](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L124#L134#L385-L396)

## Request Dispatching Mechanism

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.

1. **Host-Aware Path Extraction**: The `getPath` function (which can be customized) isolates the pathname.
2. **Matching**: The router's `match(method, path)` method returns an ordered array of handlers.
3. **Context Construction**: A `Context` object is initialized with the route matches.
4. **Handler Composition**: The `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](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L419-L427#L430)

## Route Resolution and Tie-breaking

When multiple patterns could potentially match a single incoming request (e.g., wildcards vs. exact paths), the `RegExpRouter` handles the selection process:

* **Static Path Preference**: Static routes (those without wildcards or parameters) are checked against a `staticMap` first for O(1) lookup.
* **Trie Ordering**: For parameterized routes, paths are indexed into a Trie.
* **Registration Order**: In the `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](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/router.ts#L47-L49#L62)

## Route Helpers and Introspection

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`.

| Helper | Purpose | Source |
| :--- | :--- | :--- |
| `matchedRoutes(c)` | Returns all routes that matched the current request. | [src/helper/route/index.ts:32-34](https://github.com/blade47/hono/blob/main/src/helper/route/index.ts#L32-L34) |
| `routePath(c)` | Returns the registered path for the current handler. | [src/helper/route/index.ts:58-59](https://github.com/blade47/hono/blob/main/src/helper/route/index.ts#L58-L59) |
| `baseRoutePath(c)` | Returns the base path of the route segment. | [src/helper/route/index.ts:82-83](https://github.com/blade47/hono/blob/main/src/helper/route/index.ts#L82-L83) |

## Usage Example

The following example demonstrates how to define an application, apply middleware, and use a sub-router for route grouping.

```typescript
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](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L157#L191#L208)

## Related

- [[Request Lifecycle]]
- [[Smart Router]]


---

## Request Lifecycle

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/request-lifecycle

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

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

- [src/adapter/aws-lambda/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts)
- [src/types.ts](https://github.com/blade47/hono/blob/main/src/types.ts)
- [src/context.ts](https://github.com/blade47/hono/blob/main/src/context.ts)
- [src/client/client.ts](https://github.com/blade47/hono/blob/main/src/client/client.ts)
- [src/hono-base.ts](https://github.com/blade47/hono/blob/main/src/hono-base.ts)
- [src/request.ts](https://github.com/blade47/hono/blob/main/src/request.ts)
</details>

The Request Lifecycle in Hono defines the journey of an HTTP request from its arrival in an adapter (such as AWS Lambda or a standard worker environment) to its final dispatch through the Hono router and the subsequent generation of an HTTP response. This architecture is designed to decouple the application logic from specific platform-dependent event structures, ensuring portability across cloud environments while maintaining strict performance and type-safety.

At the core of this lifecycle is the `Hono` instance, which acts as a centralized controller. When a request arrives, it is either wrapped by an adapter-specific processor or directly consumed by `app.fetch()`. The lifecycle transitions through route matching, middleware composition, handler execution, and finally, response finalization. By normalizing platform events into standard Web API `Request` objects, Hono provides a consistent interface for developers regardless of the underlying runtime.

The design emphasizes a "middleware-first" dispatching pattern. Because Hono treats handlers and middleware as fundamentally the same type (`H`), it can compose them into a unified execution chain. This choice prevents the "split-logic" problem found in other frameworks where handlers and middleware must be handled through different mechanisms, thus creating a predictable flow of execution that is highly resistant to race conditions during response generation.

## Request Normalization (Adapters)

In platform-specific environments like AWS Lambda, the request lifecycle begins with an event processor. Since different triggers (API Gateway v1/v2, ALB, Lattice) deliver event payloads in different shapes, Hono utilizes an `EventProcessor` abstract class to normalize these inputs into a standard `Request` object.

The `getProcessor` function acts as the entry point, inspecting the event object to determine the appropriate implementation. It uses platform-specific guards like `isProxyEventALB` or `isProxyEventV2` to identify the event type. Once determined, the chosen processor extracts paths, headers, and bodies—transforming them into a standard `Request` instance that the core application can understand.

Sources: [src/adapter/aws-lambda/handler.ts:639-651](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L639-L651), [src/adapter/aws-lambda/handler.ts:278-402](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L278-L402)

## Dispatch and Routing

Once a `Request` is normalized, the lifecycle moves to `app.fetch()`. This method delegates to `app.#dispatch()`, which is responsible for finding the handler for the given URL path. The router compares the request method and path against registered `RouterRoute` definitions.

The winner is chosen by the router's internal match mechanism, which returns an array of handler candidates. If multiple routes overlap, the selection is determined by the specific `Router` implementation used. The `Hono` core relies on this matching to populate the `Context` object, which encapsulates the entire state of the current request lifecycle, including environmental bindings and path parameters.

Sources: [src/hono-base.ts:406-466](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L406-L466), [src/hono-base.ts:388-397](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L388-L397)

## Middleware Composition

Hono uses a composition pattern to process requests through an ordered chain. The `compose` function processes the array of handlers returned by the router. This flow ensures that each middleware has the opportunity to perform work both before and after the next handler in the chain is executed, using the `next()` function.

> [!WARNING]
> If a developer fails to call `await next()` or return a `Response` object within the lifecycle, the framework will eventually throw an error stating the "Context is not finalized," as the chain cannot safely complete.

The lifecycle control flow follows a recursive `next()` pattern. If a handler throws an exception, the lifecycle jumps to the `errorHandler` associated with the Hono instance, which converts the error into an appropriate HTTP response, ensuring that the system never enters an unhandled state.

Sources: [src/hono-base.ts:450-466](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L450-L466), [src/hono-base.ts:406-410](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L406-L410)

## Context Encapsulation

The `Context` object is the state container for the entire request lifecycle. It is created at the start of the `#dispatch` call. Its primary responsibility is to act as a bridge between the raw `Request` and the user-land handler.

- **Storage:** It maintains a `Map` of variables (`#var`) set via `c.set()`.
- **Response Builder:** It tracks the status, headers, and the final response object.
- **Helper Methods:** Methods like `c.text()`, `c.json()`, and `c.html()` act as convenience factories that populate the `#res` property while simultaneously applying default headers (like `Content-Type`).

Sources: [src/context.ts:293-361](https://github.com/blade47/hono/blob/main/src/context.ts#L293-L361), [src/context.ts:515-780](https://github.com/blade47/hono/blob/main/src/context.ts#L515-L780)

## Response Finalization

The final phase of the lifecycle involves transforming the returned object back into a platform-compatible result. In the case of AWS Lambda, the processor’s `createResult` method handles this. It performs critical transformations:

1. **Serialization:** Converting `ArrayBuffer` or text into the format required by the gateway (sometimes requiring base64 encoding).
2. **Cookie Management:** Extracting `set-cookie` headers into the structure expected by the specific gateway version.
3. **Encoding:** Checking if the content encoding (e.g., gzip) necessitates binary handling.

Sources: [src/adapter/aws-lambda/handler.ts:344-386](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L344-L386)

## Request Lifecycle Execution Flow

The following diagram illustrates the high-level movement of a request through the Hono system.

```mermaid
flowchart TD
    A["Incoming Event (e.g., Lambda)"] --> B["EventProcessor.createRequest()"]
    B --> C["app.fetch(request)"]
    C --> D["Router.match()"]
    D --> E["compose(handlers)"]
    E --> F["Execute Middleware/Handler"]
    F --> G["Context.finalized = true"]
    G --> H["Processor.createResult()"]
    H --> I["Outgoing Response"]
```

Sources: [src/adapter/aws-lambda/handler.ts:148-157](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L148-L157), [src/hono-base.ts:406-466](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L406-L466)

## Common Utilities and Constants

| Component | Purpose |
| :--- | :--- |
| `HonoRequest` | Wraps standard `Request` with Hono-specific routing and parameter helpers. |
| `Context` | Holds the state of the current request, including bindings and response data. |
| `EventProcessor` | Normalizes platform events (AWS/Cloudflare) into a standardized interface. |
| `compose` | Executes the middleware chain using the `next()` pattern. |

Sources: [src/request.ts:19](https://github.com/blade47/hono/blob/main/src/request.ts#L19), [src/context.ts:293](https://github.com/blade47/hono/blob/main/src/context.ts#L293), [src/adapter/aws-lambda/handler.ts:278](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L278)

## Related

- [[Application Routing]]
- [[Context Execution]]


---

## Context Execution

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/context-execution

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

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

- [src/context.ts](https://github.com/blade47/hono/blob/main/src/context.ts)
- [src/adapter/aws-lambda/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts)
- [src/client/client.ts](https://github.com/blade47/hono/blob/main/src/client/client.ts)
- [src/types.ts](https://github.com/blade47/hono/blob/main/src/types.ts)
- [src/hono-base.ts](https://github.com/blade47/hono/blob/main/src/hono-base.ts)
- [src/validator/validator.ts](https://github.com/blade47/hono/blob/main/src/validator/validator.ts)
</details>

"Context Execution" refers to the Hono lifecycle management system centered on the `Context` class. It serves as the primary interface between the incoming HTTP request and the developer's handler functions. The subsystem acts as a bridge, abstracting platform-specific details (like AWS Lambda events or Cloudflare Workers `FetchEvent`) into a unified API.

The purpose of this subsystem is to provide a consistent, type-safe execution environment regardless of the deployment target. By wrapping raw requests into a `Context` instance, Hono allows middleware and handlers to interact with request data, state variables, and response generation in an identical manner, whether running in a serverless function, a standard Node server, or a browser client.

Key design decisions include a lazy-initialization pattern for heavy components like `HonoRequest` and `Headers`, ensuring that features are only processed if accessed. The `Context` object manages the state of the request/response lifecycle, tracking finalization status and providing methods to return varied content types (JSON, text, HTML).

## The `Context` Interface and Responsibilities

The `Context` class is the central orchestrator for a single execution unit. It maintains the internal state of the request-response flow, holding references to the raw request, environment bindings, and match results from the router.

### Lifecycle State and Finalization
The `Context` maintains an internal `finalized` flag (line 317) to track the state of the response. Once a handler has committed a response, the `finalized` property is set to `true` (line 433). This guard ensures that subsequent modifications, such as calling `.header()` or setting a response, operate on the already finalized object or handle the state accordingly.

> [!IMPORTANT]
> The `finalized` flag is the primary invariant for response safety. When `this.finalized` is true, attempts to modify headers force a deep-copy of the existing response to maintain functional purity while allowing late-stage modifications (lines 516-518).

## Request Processing Flow

The flow of a request starts at the application's `fetch` method and proceeds through the following orchestration chain:

1.  **Request Handling**: The `HonoBase` class's `fetch` method initiates the request handling process.
2.  **Context Initialization**: The `Context` wraps the raw `Request`. It does not immediately parse the body or headers; it uses a getter for `.req` (lines 366-369) which lazily instantiates `HonoRequest` only upon access.
3.  **Middleware Composition**: The matching handlers are combined using `compose()` (from `hono-base.ts`), which wraps the handlers into a middleware pipeline. Each handler receives the `Context` instance.
4.  **Handler Execution**: The handlers read from and write to the `Context` (using `.set()`, `.get()`, or response helpers like `.json()`).
5.  **Finalization**: The final handler returns a `Response` object, which is then returned through the pipeline and dispatched to the platform-specific adapter.

```mermaid
flowchart TD
    A[Incoming Request] --> B[Hono.fetch]
    B --> C[Router.match]
    C --> D[Context Initialization]
    D --> E[compose: Middleware Pipeline]
    E --> F[Handler Execution]
    F --> G[c.text / c.json / c.html]
    G --> H[Finalized Response]
```
Sources: [src/hono-base.ts:406-466](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L406-L466), [src/context.ts:352-361](https://github.com/blade47/hono/blob/main/src/context.ts#L352-L361)

## Adapters and Platform Integration

The `adapter/aws-lambda/handler.ts` file illustrates how the context is extended to support platform-specific triggers. The `handle` function acts as an adapter, translating incoming AWS Lambda events into the standard `Request` object expected by Hono.

- **Processors**: The adapter uses dedicated logic for different event types (`APIGatewayProxyEvent`, `ALBProxyEvent`, `LatticeProxyEventV2`). These extract `path`, `method`, `headers`, and `body` from the event and map them to standard Web `Request` types (lines 318-341).
- **Result Mapping**: After the `Context` generates a response, the adapter's `createResult` (lines 344-386) ensures the response headers and body are translated back into the structure expected by the API Gateway or Load Balancer.

## Response Helpers

The context exposes several helper methods for common HTTP operations. These methods are designed to facilitate communication.

| Method | Return Type | Purpose |
| :--- | :--- | :--- |
| `.json()` | `JSONRespondReturn` | Encodes objects to JSON and sets `Content-Type`. |
| `.text()` | `TypedResponse` | Returns a `text/plain` response. |
| `.html()` | `Response` | Returns a `text/html` response. |
| `.redirect()` | `TypedResponse` | Sets the `Location` header and a 302 status. |

These methods internally call `this.#newResponse`, which merges global state (`this.#status`, `this.#preparedHeaders`) with per-call parameters to generate the final `Response` instance (lines 604-639).

## Error Handling Mechanism

Errors within the context execution are captured by the `compose` pipeline logic defined in `hono-base.ts`. If a handler throws, the `errorHandler` function defined at the `HonoBase` level is invoked to generate a response.

> [!NOTE]
> The `Context` exposes an `.error` property (line 333). This is typically used in middleware to inspect if a handler further down the chain has triggered an exception, allowing for custom error logging without full-stop termination.

```mermaid
sequenceDiagram
    participant User
    participant Hono
    participant Handler
    User->>Hono: fetch()
    Hono->>Handler: execute()
    alt Success
        Handler-->>Hono: Response
        Hono-->>User: Response
    else Failure
        Handler-->>Hono: throw Error
        Hono->>Hono: errorHandler()
        Hono-->>User: Error Response
    end
```
Sources: [src/hono-base.ts:35-42](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L35-L42), [src/hono-base.ts:462-464](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L462-L464)

## Design Trade-offs

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| **Lazy Loading** | Minimizes memory/compute for unused context parts | Small overhead for first-time property access |
| **Class-based Context** | Encapsulated state and fluent API | Higher memory footprint per request |

## Practical Example

This snippet demonstrates how a developer uses the context within a standard route handler to set state, inspect environment variables, and return a JSON response.

```typescript
import { Hono } from 'hono'

const app = new Hono<{ Bindings: { API_KEY: string } }>()

app.get('/data', async (c) => {
  // Use .env bindings
  const apiKey = c.env.API_KEY
  
  // Set context variables
  c.set('user', { id: 1 })
  
  // Return JSON
  return c.json({ status: 'ok', data: 'hello' }, 200)
})
```
Sources: [src/context.ts:311-312](https://github.com/blade47/hono/blob/main/src/context.ts#L311-L312), [src/context.ts:541](https://github.com/blade47/hono/blob/main/src/context.ts#L541), [src/context.ts:704](https://github.com/blade47/hono/blob/main/src/context.ts#L704)

## Related

- [[Request Lifecycle]]
- [[Middleware Composition]]


---

## Middleware Composition

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/middleware-composition

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

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

- [src/types.ts](https://github.com/blade47/hono/blob/main/src/types.ts)
- [src/middleware/secure-headers/secure-headers.ts](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts)
- [src/hono-base.ts](https://github.com/blade47/hono/blob/main/src/hono-base.ts)
- [src/adapter/aws-lambda/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts)
- [src/middleware/cache/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/cache/index.ts)
- [src/middleware/compress/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/compress/index.ts)
- [src/adapter/cloudflare-pages/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/handler.ts)
- [src/middleware/combine/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/combine/index.ts)
</details>

Middleware composition in Hono is a powerful architectural pattern that allows developers to chain independent request handlers into a unified pipeline. This mechanism enables cross-cutting concerns—such as security, caching, and compression—to be applied uniformly across routes or specific path patterns without polluting individual business-logic handlers.

At its core, composition follows a "decorator-like" pattern, where each middleware has the power to pre-process requests, execute subsequent handlers via a control-flow callback function, and post-process responses. This flow allows Hono to build complex stacks of behavior that are both modular and testable, keeping the application's request-response lifecycle clean.

The subsystem serves as the glue for Hono's extensibility. By leveraging the control-flow callback pattern, composition facilitates fine-grained control over execution flow. Developers can conditionally skip middleware, intercept early responses, or perform teardown logic after other handlers have completed. This design choice is fundamental to Hono's performance, as it avoids unnecessary overhead by resolving the execution order statically during router initialization and dynamically via the `compose` pipeline during runtime dispatch.

## Pipeline Dispatch and Control Flow
Hono employs a composition pipeline to sequence handlers for a matched route. The primary flow involves receiving a `Request`, routing it to identify a set of handlers, and then executing them sequentially. Each handler receives a `Context` object and a control-flow callback function. If a handler calls this function, control is passed to the next handler in the chain.

The mechanism relies on `compose`, which wraps an array of handlers. If a request matches multiple routes, the handlers are collapsed into a single execution stream. Crucially, if a handler does not call the provided callback and provides a response, the pipeline halts, and the final response is returned to the client, effectively short-circuiting the remaining middleware.

Sources: [src/hono-base.ts:406-466](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L406-L466)

## Composable Middleware Strategies
The `combine` module provides higher-order composition primitives: `some`, `every`, and `except`. These functions act as logic gates for middleware execution.

*   `some`: Executes a list of handlers until one completes successfully. It short-circuits execution if a handler reports success (typically by returning `true`).
*   `every`: Requires all handlers to execute successfully. If any handler fails, the chain terminates.
*   `except`: Conditional execution where middleware is applied unless the `condition` (either a path string or a function) is met.

These primitives allow for sophisticated logic such as "skip authentication if the request comes from a local network" or "only run rate-limiting if the user lacks a valid bearer token."

```mermaid
flowchart TD
    A[Start] --> B{"some() logic"}
    B -->|Check Handler 1| C{Passed?}
    C -->|Yes| D[Execute callback]
    C -->|No| E[Check Handler 2]
    E --> F{Passed?}
    F -->|Yes| D
    F -->|No| G[Throw Error]
```
Sources: [src/middleware/combine/index.ts:38-164](https://github.com/blade47/hono/blob/main/src/middleware/combine/index.ts#L38-L164)

## Content-Driven Pipeline Transformations
Some middleware, like `compress`, act as stream-processing decorators. In this mechanism, the middleware calls the control-flow callback to allow the application logic to build a response, then captures that response to apply a `CompressionStream`.

This "wrap and transform" pattern is essential for modifying response bodies on the fly. The middleware must perform careful checks: it verifies that the `Content-Type` is compressible, checks for `no-transform` instructions in the `Cache-Control` header, and ensures that the response is not already compressed.

> [!IMPORTANT]
> The `compress` middleware converts strong ETags to weak ETags because the compression process alters the exact byte representation of the response body. This is a critical invariant to maintain cache consistency.

Sources: [src/middleware/compress/index.ts:86-121](https://github.com/blade47/hono/blob/main/src/middleware/compress/index.ts#L86-L121)

## Context-Aware Injection
Middleware composition frequently uses the `Context` to share state across the pipeline. For example, the `secure-headers` middleware provides a `NONCE` generator. This function checks the context for an existing nonce; if not found, it generates a new one and stores it via `ctx.set()`. This state is then accessible to downstream view engines or template renderers.

The `secureHeaders` middleware also evaluates callbacks before calling the control-flow callback, ensuring that any dependencies required by the response (like a nonce) are populated before the main handler runs, yet the final header injection happens after the main handler produces the response.

Sources: [src/middleware/secure-headers/secure-headers.ts:137-228](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts#L137-L228)

## Lifecycle Management: Cache Middleware
The `cache` middleware demonstrates a hybrid approach where it acts both as a guard and a pipeline modifier. It attempts a match against the Cache API before calling the control-flow callback. If a match exists, it terminates the request lifecycle early by returning the cached response.

If no match exists, it proceeds with the control-flow callback, waits for the application logic to populate the response, and then uses `c.executionCtx.waitUntil()` to asynchronously cache the response in the background. This ensures the request completion is not blocked by cache insertion.

```mermaid
sequenceDiagram
    participant Req as Request
    participant Mid as Cache Middleware
    participant App as Application Handler
    participant C as Cache API
    Req->>Mid: Process
    Mid->>C: match(key)
    alt Cached Response Found
        Mid-->>Req: Return Cached Response
    else No Hit
        Mid->>App: await callback()
        App-->>Mid: Return New Response
        Mid->>C: put(key, res)
        Mid-->>Req: Return Response
    end
```
Sources: [src/middleware/cache/index.ts:138-180](https://github.com/blade47/hono/blob/main/src/middleware/cache/index.ts#L138-L180)

## Performance and Selection Logics
When multiple middlewares or handlers are present, Hono manages execution priority. The router stores routes, and during dispatch, the matched route handlers are collected. The `compose` function ensures they are executed in the order of registration.

One critical safety guard exists in composition: `isNextCalled` in the `some()` implementation of the `combine` middleware. This variable prevents multiple invocations of the downstream pipeline, guaranteeing that if a condition is satisfied, the request lifecycle invariants are maintained.

> [!TIP]
> Use `combine` primitives for declarative, clean composition rather than manually tracking state across multiple `app.use()` registrations.

Sources: [src/middleware/combine/index.ts:39-68](https://github.com/blade47/hono/blob/main/src/middleware/combine/index.ts#L39-L68)

## Worked Example: Declarative Security Pipeline
This example demonstrates combining multiple security middlewares to protect an API endpoint.

```typescript
import { Hono } from 'hono'
import { secureHeaders, NONCE } from 'hono/secure-headers'
import { some } from 'hono/combine'
import { bearerAuth } from 'hono/bearer-auth'

const app = new Hono()

// Apply security headers with a custom CSP nonce
app.use(secureHeaders({
  contentSecurityPolicy: {
    scriptSrc: [NONCE],
  }
}))

// Use combined logic: skip authentication for specific paths
app.use('/api/*', some(
  (c) => c.req.path.startsWith('/api/public'),
  bearerAuth({ token: 'secret-token' })
))

app.get('/api/data', (c) => c.json({ data: 'secure' }))
```
Sources: [src/middleware/secure-headers/secure-headers.ts:184-190](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts#L184-L190), [src/middleware/combine/index.ts:38-68](https://github.com/blade47/hono/blob/main/src/middleware/combine/index.ts#L38-L68)

## Related

- [[Context Execution]]


---

## RegExp Router

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/regexp-router

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

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

- [src/types.ts](https://github.com/blade47/hono/blob/main/src/types.ts)
- [package.json](https://github.com/blade47/hono/blob/main/src/package.json)
- [src/client/client.ts](https://github.com/blade47/hono/blob/main/src/client/client.ts)
- [src/router/reg-exp-router/router.ts](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/router.ts)
- [src/preset/quick.ts](https://github.com/blade47/hono/blob/main/src/preset/quick.ts)
- [src/router/reg-exp-router/prepared-router.ts](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/prepared-router.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/linear-router/router.ts](https://github.com/blade47/hono/blob/main/src/router/linear-router/router.ts)
- [src/helper/ssg/ssg.ts](https://github.com/blade47/hono/blob/main/src/helper/ssg/ssg.ts)
</details>

The `RegExpRouter` is a high-performance routing engine designed for speed by converting standard URL routing patterns into a single, optimized regular expression. Unlike naive routers that perform linear scans or depth-first tree traversals for every incoming request, `RegExpRouter` compiles the entire routing table into a regex-based matcher. This design minimizes the per-request overhead, making it particularly effective in environments where routing performance is a critical path.

The architecture relies on a `Trie` data structure to preprocess route definitions. During the registration phase, the router tracks path structures and converts variables (like `:id`) and wildcards (`*`) into corresponding capturing groups. This structure is then serialized into a regular expression. When a request arrives, the router uses this single regex to identify the matching handler index in a single pass, significantly reducing the algorithmic complexity of route resolution.

`RegExpRouter` is one of the foundational routers used within Hono. It is typically employed by the `SmartRouter`, which combines different routing strategies to provide the best balance of flexibility and performance. By implementing the `Router` interface, it remains drop-in compatible with other routing implementations, allowing developers to switch underlying engines without altering their business logic.

## The Trie Preprocessing Mechanism

Before a regex can be generated, the router must organize the input paths into a `Trie` structure. This ensures that hierarchical path segments are handled correctly and that potential routing ambiguities are resolved. The `Trie` insertion logic acts as the primary registry for path segments.

When `add(method, path, handler)` is called:
1. The path is tokenized into segments.
2. The `Trie` structure is updated by calling `trie.insert(path, j, pathErrorCheckOnly)`.
3. If a segment contains a parameter (e.g., `:id`), it is handled by the trie nodes to facilitate correct index generation for the final regex output.

Sources: [src/router/reg-exp-router/router.ts:L132-L204](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/router.ts#L132-L187), [src/router/reg-exp-router/trie.ts](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/trie.ts)

## Regex Compilation Logic

Once all routes are registered, the `RegExpRouter` invokes `buildMatcherFromPreprocessedRoutes`. This function performs the transformation from a structured `Trie` to an executable `RegExp` instance.

The compilation process:
1. Traverses the built trie via `trie.buildRegExp()` to generate a path-matching regex.
2. Captures parameter groups so they can be extracted during the `match` operation.
3. Finalizes the regex, which acts as the "Compiled Routing Table" used to dispatch incoming requests.

```mermaid
flowchart TD
    A[Start: Build Matcher] --> B[Traverse Trie]
    B --> C[trie.buildRegExp]
    C --> D[Generate Regex Instance]
    D --> E[Finalize Handler Mapping]
    E --> F[Return Matcher]
```
Sources: [src/router/reg-exp-router/router.ts:L34-L103](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/router.ts#L34-L103)

## Static Path Handling

The `RegExpRouter` separates path matching into logic for static paths and patterns. During the build process, routes are flagged via a boolean as `!/\*|\/:/.test(route[0])`. Routes without parameters are stored as static entries. During the `match` operation, these are evaluated to ensure optimal performance for standard, non-parameterized routes.

> [!TIP]
> Placing frequently accessed static routes, such as `/health`, before dynamic routes can improve performance in high-throughput applications, as the router optimizes for these constant paths during the trie construction.

Sources: [src/router/reg-exp-router/router.ts:L43-L56](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/router.ts#L43-L56)

## Handler Selection and Tie-Breaking

When multiple handlers might match a single path (e.g., via middleware or overlapping patterns), the router must determine the order of evaluation. The `RegExpRouter` uses a sorting mechanism during the build process:

```typescript
.sort(([isStaticA, pathA], [isStaticB, pathB]) =>
  isStaticA ? 1 : isStaticB ? -1 : pathA.length - pathB.length
)
```

This logic ensures that routes are ordered such that static routes are favored and dynamic paths are ordered by their path length, establishing a consistent priority for pattern matching.

Sources: [src/router/reg-exp-router/router.ts:L47-L49](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/router.ts#L47-L49)

## The Prepared Router

For static-heavy applications, `RegExpRouter` offers a `PreparedRegExpRouter`. This variant allows the matcher to be pre-built and serialized into a string. This is useful for environments (like cold-start serverless functions) where compiling the router at runtime would be too slow.

- `buildInitParams`: Collects path data and generates the matcher.
- `serializeInitParams`: Converts the internal matcher data into a JSON string that can be safely embedded in a source file.

```mermaid
sequenceDiagram
    participant User
    participant PRR as PreparedRegExpRouter
    participant Matcher
    User->>PRR: add(method, path, handler)
    PRR->>Matcher: Access pre-compiled regex
    Matcher-->>PRR: Return index/params
    PRR->>PRR: Update handler array
```
Sources: [src/router/reg-exp-router/prepared-router.ts:L9-L93](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/prepared-router.ts#L9-L93)

## Error Handling and Invariants

The router enforces strict path invariants during construction. If a path is malformed (e.g., illegal segments), it throws an `UnsupportedPathError`. 

> [!WARNING]
> The `RegExpRouter` expects well-formed paths. If you add a path that the `Trie` cannot represent due to internal limitations, `PATH_ERROR` will be thrown, causing the router to abort the build process.

Sources: [src/router/reg-exp-router/router.ts:L63-L65](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/router.ts#L63-L65)

## Summary of Design Trade-offs

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| Regex Matching | Constant time complexity for routing | Longer initial build time |
| Trie-based pre-processing | Consistent handling of params/wildcards | Higher memory footprint during build |
| Serialization (Prepared) | Near-zero cold start time | Complex setup and build-time tooling |

Sources: [src/router/reg-exp-router/router.ts:L34-L103](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/router.ts#L34-L103), [src/router/reg-exp-router/prepared-router.ts](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/prepared-router.ts)

## Related

- [[Smart Router]]
- [[Alternative Routers]]


---

## Smart Router

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/smart-router

<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)
- [jsr.json](https://github.com/blade47/hono/blob/main/jsr.json)
- [src/hono.ts](https://github.com/blade47/hono/blob/main/src/hono.ts)
- [src/validator/validator.ts](https://github.com/blade47/hono/blob/main/src/validator/validator.ts)
- [src/preset/quick.ts](https://github.com/blade47/hono/blob/main/src/preset/quick.ts)
- [src/types.ts](https://github.com/blade47/hono/blob/main/src/types.ts)
- [src/middleware/ip-restriction/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/ip-restriction/index.ts)
- [src/router/smart-router/router.ts](https://github.com/blade47/hono/blob/main/src/router/smart-router/router.ts)
- [src/router/reg-exp-router/router.ts](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/router.ts)
- [src/utils/url.ts](https://github.com/blade47/hono/blob/main/src/utils/url.ts)
- [src/router/reg-exp-router/prepared-router.ts](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/prepared-router.ts)
</details>

The `SmartRouter` is a high-level orchestration component in the Hono framework designed to bridge the gap between multiple underlying routing strategies. Rather than forcing a singular routing algorithm (like a Trie or Regular Expression) onto all developers, it acts as a dynamic, "smart" proxy that enables Hono to optimize its routing performance based on the actual usage patterns of an application.

The core problem addressed by `SmartRouter` is the selection of the most efficient routing mechanism. Different routers perform optimally under different conditions (e.g., Trie-based routers often excel at static lookups, while RegExp-based routers offer flexibility for complex patterns). `SmartRouter` achieves this by maintaining an internal list of candidate routers and deferring the definitive choice until the first request is matched.

Upon the first request, the component iterates through its configured router implementations, attempting to register all previously queued routes sequentially into each candidate. The first router to successfully process the full routing table for the given request context is selected as the "active" router. Subsequent requests bypass the initialization logic entirely, essentially hot-swapping the `SmartRouter` instance with the performance-proven candidate.

## Design Philosophy and Router Selection

`SmartRouter` functions as a wrapper that implements the standard `Router` interface, yet hides a sophisticated "activation" phase. Its design follows a "fail-safe and promote" pattern: it maintains a list of candidate routers provided via configuration and, on the first call to `match`, attempts to populate them until one succeeds.

The mechanism uses a deferred routing strategy:
1. All `add` calls (for registering routes) are buffered in a local `private #routes` array.
2. The `match` method, when called for the first time, performs a "build" operation.
3. It iterates through the provided `routers` list, calling `add` for every buffered route on each candidate.
4. If a router successfully matches the request, that router is marked active.

> [!IMPORTANT]
> The `SmartRouter` guarantees that the router chosen is capable of handling the entire existing route set, not just the single request that triggered the selection. This ensures that the state consistency of the routing table is preserved across the transition from buffer to execution.

Sources: [src/router/smart-router/router.ts:4-32](https://github.com/blade47/hono/blob/main/src/router/smart-router/router.ts#L4-L32)

## Initialization and Lifecycle

`SmartRouter` is typically instantiated within the Hono constructor. By default, it is configured with a prioritized list (e.g., `RegExpRouter` followed by `TrieRouter`). This allows the system to attempt the most performant or generic router first.

```mermaid
classDiagram
  class Router {
    <<interface>>
    +add(method, path, handler)
    +match(method, path)
  }
  class SmartRouter {
    -routers: Router[]
    -routes: [method, path, handler][]
    +add()
    +match()
  }
  Router <|-- SmartRouter
```
Sources: [src/hono.ts:28-32](https://github.com/blade47/hono/blob/main/src/hono.ts#L28-L32)

## Call-Chain Execution: The First Match

The most complex logic within `SmartRouter` is the first-match orchestration. The control flow is explicitly designed to handle potential failures in individual router builders (like `UnsupportedPathError`).

1. **`add()`**: Buffers the route into `this.#routes`.
2. **`match()` (First invocation)**: 
   - Checks if `this.#routes` is non-null (indicating build phase).
   - Loops through `this.#routers`.
   - Calls `router.add(...)` for every entry in the buffered `routes` array.
   - Executes `router.match(method, path)`.
   - If an `UnsupportedPathError` occurs, the loop continues to the next router.
   - Upon success, it rebinds `this.match` to the active router's `match` function, effectively becoming a pass-through for subsequent requests.

Sources: [src/router/smart-router/router.ts:13-50](https://github.com/blade47/hono/blob/main/src/router/smart-router/router.ts#L13-L50)

## The Re-binding Mechanism

Once an active router is identified, `SmartRouter` modifies itself to minimize overhead for future requests. By re-binding the `match` function, it bypasses its own logic loop entirely.

```typescript
// The line that shifts responsibility from SmartRouter to the chosen implementation
this.match = router.match.bind(router);
```

This specific assignment prevents unnecessary conditional checks during the high-frequency path of route lookup, effectively turning the `SmartRouter` into a thin wrapper around the chosen router.

Sources: [src/router/smart-router/router.ts:46](https://github.com/blade47/hono/blob/main/src/router/smart-router/router.ts#L46)

## Guard Conditions and Invariants

`SmartRouter` relies on several critical invariants to maintain the integrity of the routing table:

> [!CAUTION]
> Once `match` is called, the state of the router is frozen. The check `if (!this.#routes) throw new Error(MESSAGE_MATCHER_IS_ALREADY_BUILT)` inside the `add` method prevents any further modifications to the route set after the selection of an active router has occurred.

Sources: [src/router/smart-router/router.ts:14-16](https://github.com/blade47/hono/blob/main/src/router/smart-router/router.ts#L14-L16)

## Usage Example

The following code illustrates how `SmartRouter` is initialized within the standard Hono framework instantiation.

```typescript
import { Hono } from 'hono';
import { SmartRouter } from 'hono/router/smart-router';
import { RegExpRouter } from 'hono/router/reg-exp-router';
import { TrieRouter } from 'hono/router/trie-router';

// Manual instantiation (normally handled by the Hono class)
const myRouter = new SmartRouter({
  routers: [new RegExpRouter(), new TrieRouter()]
});

const app = new Hono({ router: myRouter });

app.get('/api/users', (c) => c.json({ status: 'ok' }));
```
Sources: [src/hono.ts:26-32](https://github.com/blade47/hono/blob/main/src/hono.ts#L26-L32)

## Related

- [[RegExp Router]]
- [[Alternative Routers]]


---

## Alternative Routers

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/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]]
- [[Smart Router]]


---

## JSX Renderer

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/jsx-renderer

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

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

- [src/jsx/dom/render.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/render.ts)
- [src/context.ts](https://github.com/blade47/hono/blob/main/src/context.ts)
- [src/jsx/base.ts](https://github.com/blade47/hono/blob/main/src/jsx/base.ts)
- [src/jsx/components.ts](https://github.com/blade47/hono/blob/main/src/jsx/components.ts)
- [src/jsx/streaming.ts](https://github.com/blade47/hono/blob/main/src/jsx/streaming.ts)
- [package.json](https://github.com/blade47/hono/blob/main/package.json)
- [src/jsx/dom/intrinsic-element/components.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/intrinsic-element/components.ts)
- [src/jsx/jsx-runtime.ts](https://github.com/blade47/hono/blob/main/src/jsx/jsx-runtime.ts)
- [src/middleware/jsx-renderer/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/jsx-renderer/index.ts)
- [src/jsx/intrinsic-element/components.ts](https://github.com/blade47/hono/blob/main/src/jsx/intrinsic-element/components.ts)
- [src/jsx/context.ts](https://github.com/blade47/hono/blob/main/src/jsx/context.ts)
- [src/jsx/dom/client.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/client.ts)
- [src/utils/html.ts](https://github.com/blade47/hono/blob/main/src/utils/html.ts)
- [src/jsx/jsx-dev-runtime.ts](https://github.com/blade47/hono/blob/main/src/jsx/jsx-dev-runtime.ts)
- [src/jsx/dom/jsx-dev-runtime.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/jsx-dev-runtime.ts)
- [src/jsx/index.ts](https://github.com/blade47/hono/blob/main/src/jsx/index.ts)
- [src/jsx/dom/jsx-runtime.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/jsx-runtime.ts)
- [src/helper/html/index.ts](https://github.com/blade47/hono/blob/main/src/helper/html/index.ts)
- [src/jsx/dom/server.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/server.ts)
- [src/jsx/dom/css.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/css.ts)
- [src/jsx/dom/index.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/index.ts)
- [runtime-tests/deno-jsx/deno.react-jsx.json](https://github.com/blade47/hono/blob/main/runtime-tests/deno-jsx/deno.react-jsx.json)
- [runtime-tests/deno-jsx/deno.precompile.json](https://github.com/blade47/hono/blob/main/runtime-tests/deno-jsx/deno.precompile.json)
- [src/jsx/dom/components.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/components.ts)
- [runtime-tests/deno/deno.json](https://github.com/blade47/hono/blob/main/runtime-tests/deno/deno.json)
- [jsr.json](https://github.com/blade47/hono/blob/main/jsr.json)
- [src/jsx/types.ts](https://github.com/blade47/hono/blob/main/src/jsx/types.ts)
- [src/jsx/intrinsic-elements.ts](https://github.com/blade47/hono/blob/main/src/jsx/intrinsic-elements.ts)
</details>

The JSX Renderer is the core component within the Hono framework responsible for converting JSX structures into actionable DOM elements (client-side) or serialized HTML (server-side). Unlike standard virtual DOM libraries that might prioritize universal hydration, the Hono JSX renderer is specifically architected to be lightweight, fast, and highly compatible with Hono's middleware-based request pipeline, facilitating both traditional server-side rendering (SSR) and modern dynamic DOM updates.

At its core, the system distinguishes between a static "base" JSX representation (used for initial serialization) and a "DOM" renderer that enables reactive, stateful updates. The renderer uses a custom reconciliation process that minimizes DOM manipulation by intelligently tracking component hierarchies, context, and hook state. By leveraging specialized internal tags and efficient property application, it ensures that changes to application state translate directly into optimized instructions for the underlying web browser.

The JSX Renderer is deeply integrated into Hono's `context.ts` and middleware systems. It provides the mechanism by which handlers can respond with complex HTML structures while maintaining the ability to inject dynamic metadata or perform streaming rendering, effectively bridging the gap between static HTML generation and interactive client-side application state.

## The Reconciliation Algorithm: Build and Apply

The rendering mechanism is split into two primary phases: `build` (determining what should change) and `apply` (executing those changes against the real DOM).

```mermaid
flowchart TD
    A["Trigger Update"] --> B["build(context, node)"]
    B --> C{"Invoke Tags<br/>and Reconcile Children"}
    C --> D["Calculate<br/>vR (nodes to remove)"]
    D --> E["apply(node, container)"]
    E --> F["Update<br/>Actual DOM"]
```
Sources: [src/jsx/dom/render.ts:497-665](https://github.com/blade47/hono/blob/main/src/jsx/dom/render.ts#L497-L665), [src/jsx/dom/render.ts:387-481](https://github.com/blade47/hono/blob/main/src/jsx/dom/render.ts#L387-L481)

The `build` phase recursively traverses the component tree. When a component function is invoked, the renderer checks if its output matches the previous state. If an old version of the node exists, it performs a key-based lookup to find a match and attempts to patch properties rather than recreate elements. If no match is found, the node is marked for creation.

> [!CAUTION]
> If a node lacks a `key`, the renderer reconciles children based strictly on their `tag`. This requires caution: switching components of the same tag type but different underlying implementation can lead to stale state being preserved in the stash.

Sources: [src/jsx/dom/render.ts:541-555](https://github.com/blade47/hono/blob/main/src/jsx/dom/render.ts#L541-L555)

The `apply` phase then consumes the children lists populated by the `build` phase. It maps these internal virtual nodes to browser-native `HTMLElement` instances. For efficiency, it performs property application by comparing `attributes` against `oldAttributes`, updating event listeners (using a `getEventSpec` lookup table) and styles dynamically.

## Lifecycle and Effect Management

The renderer supports lifecycle hooks (`useEffect`, `useLayoutEffect`, `useInsertionEffect`) by batching these callbacks in the `apply` phase. Once the DOM is updated, the renderer processes the collected effects, ensuring that `useInsertionEffect` runs first, followed by `useLayoutEffect`, and finally scheduling `useEffect` inside a `requestAnimationFrame`.

| Hook Type | Timing |
| :--- | :--- |
| `useInsertionEffect` | Before DOM mutations/layouts |
| `useLayoutEffect` | After DOM updates but before paint |
| `useEffect` | After paint (scheduled via `requestAnimationFrame`) |

Sources: [src/jsx/dom/render.ts:462-480](https://github.com/blade47/hono/blob/main/src/jsx/dom/render.ts#L462-L480)

## Middleware Integration: `jsxRenderer`

The `jsxRenderer` middleware integrates the JSX rendering system into the broader Hono request lifecycle. It allows developers to register a layout component that wraps every `c.render()` call. 

```typescript
// Example of how the jsxRenderer middleware is used to register a layout
app.get(
  '/page/*',
  jsxRenderer(({ children, Layout }) => {
    return (
      <Layout>
        <body>{children}</body>
      </Layout>
    )
  })
)
```
Sources: [src/middleware/jsx-renderer/index.ts:116-129](https://github.com/blade47/hono/blob/main/src/middleware/jsx-renderer/index.ts#L116-L129)

This middleware uses the `createRenderer` function, which binds the `Context` and `Layout` to the `render` function provided to the user. When `c.render()` is called, it constructs the component tree with a `RequestContext.Provider`, ensuring that downstream components can access the `Hono` context object directly via `useRequestContext()`.

Sources: [src/middleware/jsx-renderer/index.ts:33-80](https://github.com/blade47/hono/blob/main/src/middleware/jsx-renderer/index.ts#L33-L80)

## Performance Considerations

The renderer employs several strategies to maintain performance:
1. **Try-Catch Attribute Validation**: Instead of regex-validating every attribute name before application, the renderer applies them and only traps errors (e.g., `InvalidCharacterError`) at the point of application. This makes common-path rendering significantly faster.
2. **Event Caching**: The `eventCache` object pre-defines frequently used events like `onClick` to avoid repeated regex matching for standard DOM handlers.
3. **Memoization Support**: The `memo` utility uses a `DOM_MEMO` property on components. The reconciler checks this function before proceeding with a sub-tree update, allowing components to skip rendering entirely if properties remain stable.

Sources: [src/jsx/dom/render.ts:158-163](https://github.com/blade47/hono/blob/main/src/jsx/dom/render.ts#L158-L163), [src/jsx/dom/render.ts:115-118](https://github.com/blade47/hono/blob/main/src/jsx/dom/render.ts#L115-L118), [src/jsx/base.ts:384-405](https://github.com/blade47/hono/blob/main/src/jsx/base.ts#L384-L405)

## Related

- [[DOM Rendering]]
- [[Streaming Utilities]]


---

## DOM Rendering

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/dom-rendering

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

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

- [src/jsx/dom/render.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/render.ts)
- [src/jsx/base.ts](https://github.com/blade47/hono/blob/main/src/jsx/base.ts)
- [src/context.ts](https://github.com/blade47/hono/blob/main/src/context.ts)
- [src/jsx/hooks/index.ts](https://github.com/blade47/hono/blob/main/src/jsx/hooks/index.ts)
- [src/jsx/streaming.ts](https://github.com/blade47/hono/blob/main/src/jsx/streaming.ts)
- [src/jsx/components.ts](https://github.com/blade47/hono/blob/main/src/jsx/components.ts)
- [src/jsx/dom/intrinsic-element/components.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/intrinsic-element/components.ts)
- [src/jsx/dom/client.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/client.ts)
- [src/jsx/intrinsic-element/components.ts](https://github.com/blade47/hono/blob/main/src/jsx/intrinsic-element/components.ts)
- [src/middleware/jsx-renderer/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/jsx-renderer/index.ts)
- [src/jsx/jsx-runtime.ts](https://github.com/blade47/hono/blob/main/src/jsx/jsx-runtime.ts)
- [src/jsx/context.ts](https://github.com/blade47/hono/blob/main/src/jsx/context.ts)
- [src/jsx/dom/server.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/server.ts)
- [src/jsx/dom/index.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/index.ts)
- [src/jsx/dom/css.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/css.ts)
- [src/jsx/index.ts](https://github.com/blade47/hono/blob/main/src/jsx/index.ts)
- [src/jsx/dom/jsx-runtime.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/jsx-runtime.ts)
- [src/jsx/dom/jsx-dev-runtime.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/jsx-dev-runtime.ts)
- [src/utils/html.ts](https://github.com/blade47/hono/blob/main/src/utils/html.ts)
- [src/jsx/jsx-dev-runtime.ts](https://github.com/blade47/hono/blob/main/src/jsx/jsx-dev-runtime.ts)
- [src/hono-base.ts](https://github.com/blade47/hono/blob/main/src/hono-base.ts)
- [src/helper/css/index.ts](https://github.com/blade47/hono/blob/main/src/helper/css/index.ts)
- [src/jsx/dom/components.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/components.ts)
- [src/jsx/types.ts](https://github.com/blade47/hono/blob/main/src/jsx/types.ts)
- [src/jsx/intrinsic-elements.ts](https://github.com/blade47/hono/blob/main/src/jsx/intrinsic-elements.ts)
</details>

DOM Rendering is a lightweight, runtime-focused engine within the Hono framework designed to bridge the gap between declarative JSX templates and imperative browser DOM manipulations. Unlike server-side rendering (SSR) implementations that serialize JSX into HTML strings, this subsystem maintains an internal virtual-tree representation of nodes, enabling efficient updates, hook management, and dynamic interaction within the client-side environment. It is the core mechanism that allows Hono applications to remain responsive without the overhead of heavy virtual DOM reconciliation found in traditional libraries.

The architecture centers around the `Node` structure—a unified interface that distinguishes between static text nodes and interactive element nodes. By tracking previous props (`pP`) and virtual children (`vC`), the renderer minimizes browser reflows through surgical DOM updates. It supports React-like hooks such as `useState`, `useEffect`, and `useMemo`, which are integrated directly into the lifecycle of each node object, allowing state-driven UI updates to occur precisely where needed without traversing the entire component tree.

Interaction with the system is typically handled through the `render()` or `hydrateRoot()` APIs, which initiate the transformation of a JSX structure into a live DOM tree. Once rendered, the renderer automatically manages effect cleanup, event binding, and context propagation, ensuring that declarative updates result in predictable DOM transitions. This design prioritizes runtime performance, using native browser capabilities and minimal overhead to handle the complexities of component-based UI development.

## The Node Object Model
The core of the DOM renderer is the `NodeObject` type, a recursive data structure representing an element in the DOM tree. Unlike a simple HTML string, the `NodeObject` caches runtime metadata required for reconciliation and reactive updates.

| Field | Purpose |
| :--- | :--- |
| `props` | Current component properties. |
| `pP` | Previous properties, used to detect changes for incremental updates. |
| `vC` | Virtual children: an array of nested `Node` instances. |
| `e` | The live `SupportedElement` or `Text` node associated with this entry. |
| `c` | The parent `Container` (HTMLElement or DocumentFragment). |
| `s` | A flag indicating whether to skip build/apply steps (performance optimization). |
| `[DOM_STASH]` | An internal storage array for hooks (index, effects, context). |

Sources: [src/jsx/dom/render.ts:41-65](https://github.com/blade47/hono/blob/main/src/jsx/dom/render.ts#L41-L65)

## Control Flow: Reconciliation and Building
The renderer process uses a two-phase cycle: `build` (determining the structure) and `apply` (syncing that structure to the live DOM). The `build` function recursively transforms JSX nodes into the `Node` internal representation.

When a node requires an update, the renderer uses a `WeakMap` (`updateMap`) to consolidate pending changes, ensuring that rapid state updates trigger only the necessary re-rendering. During the `build` phase, the system maintains a `buildDataStack` to track the context and the current node being processed, which is essential for `useContext` and hook initialization.

```mermaid
flowchart TD
    A["Render Call"] --> B["Build Phase"]
    B --> C["Recursive VDOM Construction"]
    C --> D["Identify Changes (Diffing)"]
    D --> E["Apply Phase"]
    E --> F["DOM Mutation (Append/Insert/Update)"]
    F --> G["Execute Effects (useEffect/useLayoutEffect)"]
```
Sources: [src/jsx/dom/render.ts:497-665](https://github.com/blade47/hono/blob/main/src/jsx/dom/render.ts#L497-L665), [src/jsx/dom/render.ts:740-781](https://github.com/blade47/hono/blob/main/src/jsx/dom/render.ts#L740-L781)

## Hook Execution and Lifecycle
Hooks are indexed within the `[DOM_STASH]` field of a `NodeObject`. The system utilizes a `current hook index` to ensure that consecutive calls to hooks within a component remain synchronized across re-renders.

> [!NOTE]
> `useEffect` callbacks are scheduled via `requestAnimationFrame` to decouple DOM mutations from effect execution, while `useLayoutEffect` runs synchronously after the DOM is updated but before the browser paints.

The system ensures correct cleanup via the `removeNode` function, which explicitly triggers registered effect cleanups and clears references stored in the `refCleanupMap`.

Sources: [src/jsx/dom/render.ts:341-362](https://github.com/blade47/hono/blob/main/src/jsx/dom/render.ts#L341-L362), [src/jsx/hooks/index.ts:260-287](https://github.com/blade47/hono/blob/main/src/jsx/hooks/index.ts#L260-L287)

## Attribute and Event Handling
The renderer optimizes property application by distinguishing between event listeners, special attributes (like `dangerouslySetInnerHTML`), and standard DOM attributes.

- **Event Delegation:** Attributes starting with "on" (e.g., `onClick`) are parsed into `[eventName, capture]` pairs. The system maintains an `eventCache` for frequently used events to speed up lookups.
- **Form Values:** Special handling is provided for `SELECT` and `INPUT` fields, where `applySelectValue` or direct property assignment is used instead of standard `setAttribute` to reflect internal states like `selectedIndex` or `checked`.
- **Attribute Application:** Standard attributes are set using `container.setAttribute`. The renderer uses a `try-catch` block around `setAttribute` specifically to catch `InvalidCharacterError`, avoiding a slow upfront regex validation of every attribute name.

Sources: [src/jsx/dom/render.ts:115-132](https://github.com/blade47/hono/blob/main/src/jsx/dom/render.ts#L115-L132), [src/jsx/dom/render.ts:164-272](https://github.com/blade47/hono/blob/main/src/jsx/dom/render.ts#L164-L272)

## Error Boundaries and Streaming
The DOM renderer integrates with `ErrorBoundary` components by maintaining an error stack in the `Context`. When a component throws an error, the renderer looks for the closest `DOM_ERROR_HANDLER` in the hierarchy.

If an error boundary is found, the system wraps the fallback in an update queue. This allows the boundary to recover gracefully. The renderer uses a `cancelBuild` symbol to halt the reconciliation process for subtrees that have crashed, preventing them from contaminating the global DOM state until a recovery render is triggered.

Sources: [src/jsx/dom/render.ts:612-657](https://github.com/blade47/hono/blob/main/src/jsx/dom/render.ts#L612-L657)

## Worked Example: Client-Side Rendering
To render an application, use the `createRoot` API. This pattern creates a consistent root-level controller that can manage subsequent updates via `useState`.

```typescript
import { createRoot } from 'hono/jsx/dom/client';

const App = ({ name }: { name: string }) => <h1>Hello {name}</h1>;

const root = createRoot(document.getElementById('root')!);
root.render(<App name="Hono" />);

// Later, trigger an update if the component was setup to be reactive
```
Sources: [src/jsx/dom/client.ts:23-66](https://github.com/blade47/hono/blob/main/src/jsx/dom/client.ts#L23-L66)

## Related

- [[JSX Renderer]]


---

## Streaming Utilities

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/streaming-utilities

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

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

- [src/context.ts](https://github.com/blade47/hono/blob/main/src/context.ts)
- [src/jsx/dom/render.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/render.ts)
- [src/adapter/aws-lambda/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts)
- [src/jsx/streaming.ts](https://github.com/blade47/hono/blob/main/src/jsx/streaming.ts)
- [src/helper/streaming/stream.ts](https://github.com/blade47/hono/blob/main/src/helper/streaming/stream.ts)
- [src/helper/streaming/sse.ts](https://github.com/blade47/hono/blob/main/src/helper/streaming/sse.ts)
- [src/jsx/components.ts](https://github.com/blade47/hono/blob/main/src/jsx/components.ts)
- [src/middleware/compress/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/compress/index.ts)
- [src/utils/stream.ts](https://github.com/blade47/hono/blob/main/src/utils/stream.ts)
- [src/middleware/jsx-renderer/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/jsx-renderer/index.ts)
- [src/helper/proxy/index.ts](https://github.com/blade47/hono/blob/main/src/helper/proxy/index.ts)
- [src/request.ts](https://github.com/blade47/hono/blob/main/src/request.ts)
- [src/adapter/lambda-edge/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/lambda-edge/handler.ts)
- [src/jsx/base.ts](https://github.com/blade47/hono/blob/main/src/jsx/base.ts)
- [src/middleware/etag/digest.ts](https://github.com/blade47/hono/blob/main/src/middleware/etag/digest.ts)
- [src/middleware/body-limit/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/body-limit/index.ts)
- [src/helper/streaming/index.ts](https://github.com/blade47/hono/blob/main/src/helper/streaming/index.ts)
- [src/utils/html.ts](https://github.com/blade47/hono/blob/main/src/utils/html.ts)
- [src/jsx/dom/server.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/server.ts)
- [src/client/fetch-result-please.ts](https://github.com/blade47/hono/blob/main/src/client/fetch-result-please.ts)
- [src/jsx/jsx-runtime.ts](https://github.com/blade47/hono/blob/main/src/jsx/jsx-runtime.ts)
- [src/helper/streaming/text.ts](https://github.com/blade47/hono/blob/main/src/helper/streaming/text.ts)
- [src/helper/ssg/ssg.ts](https://github.com/blade47/hono/blob/main/src/helper/ssg/ssg.ts)
- [src/hono-base.ts](https://github.com/blade47/hono/blob/main/src/hono-base.ts)
- [src/jsx/dom/client.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/client.ts)
</details>

Streaming Utilities in Hono provide the infrastructure necessary for handling long-lived HTTP responses, server-sent events (SSE), and incremental rendering of HTML. By leveraging standard `ReadableStream` and `WritableStream` primitives, these utilities enable efficient, non-blocking data delivery, which is critical for real-time applications and optimized web performance.

At the architecture level, Hono abstracts the low-level complexities of stream management and browser-to-server connection handling. The primary objective is to allow developers to transmit data to the client as it becomes available, rather than waiting for an entire document or payload to be generated. This is achieved through a consistent interface that sits atop standard web APIs, ensuring compatibility across different JavaScript runtimes like Cloudflare Workers, Node.js, and Bun.

These utilities are deeply integrated into the Hono request/response lifecycle. Components like `StreamingApi` and `SSEStreamingApi` manage the communication pipes, while high-level helpers like `stream`, `streamText`, and `streamSSE` simplify the orchestration of these pipes. By centralizing the logic for chunked encoding, cleanup of abort events, and error propagation, these utilities ensure that streaming remains predictable and memory-efficient.

## Core Streaming API Surface

The `StreamingApi` class provides the foundational interface for writing chunks to an underlying `WritableStream`. It handles the conversion of strings to byte buffers, supports `writeln` for convenience, and maintains internal flags to track the stream's state, preventing redundant or erroneous operations once a stream has been aborted or closed.

```mermaid
classDiagram
    class StreamingApi {
        -writer: WritableStreamDefaultWriter
        +responseReadable: ReadableStream
        +aborted: boolean
        +closed: boolean
        +write(input)
        +writeln(input)
        +close()
        +abort()
    }
    class SSEStreamingApi {
        +writeSSE(message)
    }
    StreamingApi <|-- SSEStreamingApi
```
Sources: [src/utils/stream.ts:6-98](https://github.com/blade47/hono/blob/main/src/utils/stream.ts#L6-L98), [src/helper/streaming/sse.ts:13-45](https://github.com/blade47/hono/blob/main/src/helper/streaming/sse.ts#L13-L45)

## Server-Sent Events (SSE) Mechanism

The SSE implementation extends the base streaming API to enforce the specific format required by the SSE protocol (`data:`, `event:`, `id:`, etc.). The `writeSSE` method performs validation to ensure that headers like `event` or `id` do not contain illegal newline characters, which would terminate the message prematurely.

> [!WARNING]
> SSE message fields must not contain `\r` or `\n`. The `writeSSE` method throws an `Error` if these characters are detected in `event`, `id`, or `retry` fields to ensure protocol integrity.

Sources: [src/helper/streaming/sse.ts:18-44](https://github.com/blade47/hono/blob/main/src/helper/streaming/sse.ts#L18-L44)

## Stream Lifecycle and Bun Compatibility

Streaming in Hono includes specific handling for platform inconsistencies, particularly regarding the `ReadableStream` lifecycle. In older versions of Bun, the `ReadableStream` used for response objects was not always automatically cancelled upon request abort. The `stream` and `streamSSE` helpers add event listeners to the request signal to manually invoke `stream.abort()` when an abort event occurs.

```mermaid
flowchart TD
    A["Request received"] --> B{"Is old Bun version?"}
    B -- Yes --> C["Add signal abort listener"]
    B -- No --> D["Create TransformStream"]
    C --> D
    D --> E["Create StreamingApi"]
    E --> F["Start async cb(stream)"]
    F --> G["return c.newResponse(stream.responseReadable)"]
```
Sources: [src/helper/streaming/stream.ts:15-22](https://github.com/blade47/hono/blob/main/src/helper/streaming/stream.ts#L15-L22), [src/helper/streaming/sse.ts:80-87](https://github.com/blade47/hono/blob/main/src/helper/streaming/sse.ts#L80-L87)

## Incremental JSX Rendering

The `renderToReadableStream` function allows for incremental generation of HTML content from JSX trees. It tracks dependencies (callbacks) and resolves them as they become available. This mechanism is the backbone of Hono's streaming support for JSX, enabling components to suspend rendering until data is fetched.

> [!NOTE]
> `renderToReadableStream` monitors `cancelled` status on each tick. If a stream is cancelled, it stops pushing data, which prevents memory leaks or unnecessary processing in the middle of long-running rendering tasks.

Sources: [src/jsx/streaming.ts:142-216](https://github.com/blade47/hono/blob/main/src/jsx/streaming.ts#L142-L216)

## Error Handling and Cleanup

Error handling is implemented through standard try-catch-finally patterns in the main runner functions (`run` for SSE and anonymous wrappers for general streams). When an error occurs in the callback, the `onError` hook is triggered.

| Hook Type | Responsibility |
| :--- | :--- |
| `onError` | Receives the `Error` and `StreamingApi` instance to perform custom error logic or logging. |
| `Finally` block | Guarantees that `stream.close()` is called regardless of execution success, ensuring resource cleanup. |

Sources: [src/helper/streaming/stream.ts:26-42](https://github.com/blade47/hono/blob/main/src/helper/streaming/stream.ts#L26-L42), [src/helper/streaming/sse.ts:47-68](https://github.com/blade47/hono/blob/main/src/helper/streaming/sse.ts#L47-L68)

## Usage Example: Basic Text Streaming

The following example shows how to use the `streamText` utility to push data to the client incrementally.

```typescript
import { Hono } from 'hono'
import { streamText } from 'hono/streaming'

const app = new Hono()

app.get('/stream', (c) => {
  return streamText(c, async (stream) => {
    await stream.writeln('Starting stream...')
    await stream.sleep(1000)
    await stream.write('Streaming complete.')
  })
})
```
Sources: [src/helper/streaming/text.ts:6-15](https://github.com/blade47/hono/blob/main/src/helper/streaming/text.ts#L6-L15)

## Related

- [[JSX Renderer]]


---

## CSS Styling

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/css-styling

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

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

- [src/middleware/secure-headers/secure-headers.ts](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts)
- [package.json](https://github.com/blade47/hono/blob/main/package.json)
- [src/helper/css/common.ts](https://github.com/blade47/hono/blob/main/src/helper/css/common.ts)
- [src/jsx/dom/render.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/render.ts)
- [src/helper/css/index.ts](https://github.com/blade47/hono/blob/main/src/helper/css/index.ts)
- [src/jsx/streaming.ts](https://github.com/blade47/hono/blob/main/src/jsx/streaming.ts)
- [src/jsx/utils.ts](https://github.com/blade47/hono/blob/main/src/jsx/utils.ts)
- [src/jsx/dom/css.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/css.ts)
- [src/middleware/compress/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/compress/index.ts)
- [src/jsx/components.ts](https://github.com/blade47/hono/blob/main/src/jsx/components.ts)
- [src/jsx/dom/intrinsic-element/components.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/intrinsic-element/components.ts)
- [src/helper/ssg/ssg.ts](https://github.com/blade47/hono/blob/main/src/helper/ssg/ssg.ts)
- [src/jsx/intrinsic-element/components.ts](https://github.com/blade47/hono/blob/main/src/jsx/intrinsic-element/components.ts)
- [src/jsx/base.ts](https://github.com/blade47/hono/blob/main/src/jsx/base.ts)
- [src/utils/html.ts](https://github.com/blade47/hono/blob/main/src/utils/html.ts)
- [jsr.json](https://github.com/blade47/hono/blob/main/jsr.json)
- [src/jsx/jsx-runtime.ts](https://github.com/blade47/hono/blob/main/src/jsx/jsx-runtime.ts)
- [src/helper/html/index.ts](https://github.com/blade47/hono/blob/main/src/helper/html/index.ts)
- [src/helper/ssg/utils.ts](https://github.com/blade47/hono/blob/main/src/helper/ssg/utils.ts)
- [src/helper/dev/index.ts](https://github.com/blade47/hono/blob/main/src/helper/dev/index.ts)
- [src/middleware/jsx-renderer/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/jsx-renderer/index.ts)
- [src/jsx/intrinsic-element/common.ts](https://github.com/blade47/hono/blob/main/src/jsx/intrinsic-element/common.ts)
- [src/helper/ssg/index.ts](https://github.com/blade47/hono/blob/main/src/helper/ssg/index.ts)
- [src/adapter/deno/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/deno/index.ts)
- [src/jsx/index.ts](https://github.com/blade47/hono/blob/main/src/jsx/index.ts)
- [src/utils/compress.ts](https://github.com/blade47/hono/blob/main/src/utils/compress.ts)
- [src/jsx/jsx-dev-runtime.ts](https://github.com/blade47/hono/blob/main/src/jsx/jsx-dev-runtime.ts)
</details>

Hono provides a robust, experimental CSS-in-JS solution designed to work seamlessly in both server-side rendering (SSR) and client-side DOM environments. This subsystem addresses the challenge of managing scoped styles in a modular application by generating hash-based class names at runtime, minimizing style collisions, and supporting efficient style injection.

At its core, the CSS styling mechanism treats CSS rules as structured data. By utilizing template literals, it allows developers to define styles naturally, while the underlying helper functions transform these templates into minified style strings and associated class name objects. These objects encapsulate selectors, class identifiers, and the actual style string, which are then used by the rendering engine to either inject standard `<style>` tags during SSR or dynamically update the document’s stylesheet via `CSSStyleSheet` in the DOM.

The system is highly integrated with Hono’s JSX ecosystem. When used in a server environment, the styling helper manages style injection through callback mechanisms that hook into the HTML string rendering flow. In the browser, the DOM-specific CSS module provides an efficient bridge to the browser’s native CSS Object Model (CSSOM). This dual-mode approach ensures that whether the site is served via static generation or dynamic requests, styles are handled in a performant, scoped-by-default, and standard-compliant manner.

## Style String Minification

The subsystem includes a robust minification engine that operates directly on the raw CSS template string. It uses a series of regular expressions to strip unnecessary whitespace, comments, and redundant semicolons, effectively reducing the payload size before the styles are rendered into the final output.

The `minify` function utilizes a complex regex `minifyCssRe` that matches string literals as a protected group to ensure that content inside quotes is not unintentionally modified during the stripping process.

```typescript
// Example of the minification mechanism logic
export const minify = (css: string): string => {
  return css.replace(minifyCssRe, (_, $1, $2, $3, $4) => $1 || $2 || $3 || $4 || '')
}
```
Sources: [src/helper/css/common.ts:100-102](https://github.com/blade47/hono/blob/main/src/helper/css/common.ts#L100-L102)

## Context-Aware Style Management

The `createCssContext` function is the factory that configures the styling environment. It manages state between renders via a `WeakMap`, allowing the engine to track which class names have already been injected into the current request context.

During SSR, if a style has not been rendered yet, a callback is registered. When the stream is finalized, this callback resolves the missing styles and injects them into the document, ensuring that only necessary styles are shipped.

```mermaid
flowchart TD
    A[Render Request] --> B{Style in Context?}
    B -- Yes --> C[Return cached class name]
    B -- No --> D[Register CSS injection callback]
    D --> E[Inject style via <style> tag or script]
```
Sources: [src/helper/css/index.ts:71-122](https://github.com/blade47/hono/blob/main/src/helper/css/index.ts#L71-L122)

## CSSOM Injection Strategy

In the DOM environment, the CSS styling mechanism bypasses standard string injection in favor of direct manipulation of `CSSStyleSheet`. The `createCssJsxDomObjects` function manages a singleton stylesheet entry for the application.

1. `findStyleSheet` attempts to locate the `<style>` tag by ID.
2. If found, it attaches a `Set` to the object to track `addedStyles` locally, preventing duplicate rule insertions.
3. The `insertRule` function uses `sheet.insertRule` to push new definitions to the browser engine, which is significantly faster than DOM tree manipulation for high-frequency style updates.

> [!NOTE]
> The styling subsystem uses a specific internal identifier, `DEFAULT_STYLE_ID` ('hono-css'), to locate or create the `<style>` tag used for injection.

Sources: [src/jsx/dom/css.ts:77-113](https://github.com/blade47/hono/blob/main/src/jsx/dom/css.ts#L77-L113)

## Usage Example

The following example demonstrates how to define scoped styles using the CSS helper and apply them to JSX components.

```typescript
import { css, cx } from 'hono/css'

const buttonClass = css`
  /* Custom label */
  background-color: blue;
  color: white;
  padding: 10px;
`

export const App = () => (
  <button className={cx(buttonClass, 'my-other-class')}>
    Click Me
  </button>
)
```
Sources: [src/helper/css/index.ts:224-231](https://github.com/blade47/hono/blob/main/src/helper/css/index.ts#L224-L231)

## Design Trade-offs

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| **Hash-based naming** | Guaranteed uniqueness, avoids style leaks | Slightly longer CSS file/style tags |
| **Runtime Minification** | Clean output even with messy templates | Slight CPU overhead during first render |
| **WeakMap for Context** | Efficient garbage collection of contexts | Requires object references for context storage |

Sources: [src/helper/css/common.ts:43-50](https://github.com/blade47/hono/blob/main/src/helper/css/common.ts#L43-L50), [src/helper/css/index.ts:82-83](https://github.com/blade47/hono/blob/main/src/helper/css/index.ts#L82-L83)

## Related

- [[JSX Renderer]]


---

## Runtime Adapters

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/runtime-adapters

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

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

- [src/adapter/aws-lambda/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts)
- [package.json](https://github.com/blade47/hono/blob/main/package.json)
- [src/hono-base.ts](https://github.com/blade47/hono/blob/main/src/hono-base.ts)
- [src/context.ts](https://github.com/blade47/hono/blob/main/src/context.ts)
- [src/adapter/cloudflare-pages/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/handler.ts)
- [src/adapter/lambda-edge/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/lambda-edge/handler.ts)
- [src/preset/quick.ts](https://github.com/blade47/hono/blob/main/src/preset/quick.ts)
- [src/hono.ts](https://github.com/blade47/hono/blob/main/src/hono.ts)
- [src/jsx/streaming.ts](https://github.com/blade47/hono/blob/main/src/jsx/streaming.ts)
- [src/helper/proxy/index.ts](https://github.com/blade47/hono/blob/main/src/helper/proxy/index.ts)
- [src/helper/adapter/index.ts](https://github.com/blade47/hono/blob/main/src/helper/adapter/index.ts)
- [src/adapter/netlify/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/netlify/handler.ts)
- [src/preset/tiny.ts](https://github.com/blade47/hono/blob/main/src/preset/tiny.ts)
- [src/jsx/jsx-runtime.ts](https://github.com/blade47/hono/blob/main/src/jsx/jsx-runtime.ts)
- [src/adapter/vercel/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/vercel/handler.ts)
- [src/middleware/jsx-renderer/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/jsx-renderer/index.ts)
- [src/adapter/cloudflare-pages/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/index.ts)
- [src/adapter/cloudflare-workers/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-workers/index.ts)
- [runtime-tests/workerd/index.ts](https://github.com/blade47/hono/blob/main/runtime-tests/workerd/index.ts)
- [src/adapter/lambda-edge/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/lambda-edge/index.ts)
- [src/adapter/deno/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/deno/index.ts)
- [src/adapter/service-worker/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/service-worker/handler.ts)
- [src/adapter/service-worker/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/service-worker/index.ts)
- [src/adapter/vercel/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/vercel/index.ts)
- [src/adapter/cloudflare-workers/websocket.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-workers/websocket.ts)
- [src/adapter/cloudflare-pages/conninfo.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/conninfo.ts)
- [src/adapter/bun/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/bun/index.ts)
- [src/adapter/aws-lambda/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/index.ts)
- [runtime-tests/deno/deno.json](https://github.com/blade47/hono/blob/main/runtime-tests/deno/deno.json)
- [src/adapter/netlify/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/netlify/index.ts)
</details>

Hono is built on Web Standards, which allows it to run across diverse JavaScript runtimes. Runtime Adapters are the bridges that enable Hono to integrate into specific hosting environments, such as AWS Lambda, Cloudflare Workers, or Deno. These adapters perform the translation work between platform-specific event objects and the standard `Request` and `Response` objects that Hono expects.

The design philosophy of Hono is to abstract away the platform's entry point, enabling developers to write code that is largely environment-agnostic. When a request hits a platform, the adapter is responsible for creating a `Request` instance, executing the `app.fetch` entry point, and then transforming the resulting `Response` back into the format expected by the host.

By encapsulating these platform details, Hono avoids coupling core logic to any single vendor's API. This makes the system modular: adding support for a new serverless function provider involves implementing a small adapter wrapper while the business logic remains identical across targets.

## Edge Adapters

Edge Adapters target platforms like Cloudflare Workers, Deno, and Lambda@Edge. These environments prioritize fast execution and typically interact with global `Request`/`Response` objects natively. The architecture focuses on minimal overhead, directly passing the platform’s request object to the Hono instance.

In Cloudflare Workers or Deno, the adapter is often light, providing helper utilities for platform-specific capabilities like WebSockets or connection info. For instance, `upgradeWebSocket` in the Cloudflare Workers adapter handles the `WebSocketPair` and protocol handshakes, integrating them into Hono's `WSContext`.

```mermaid
flowchart LR
    A[Platform Request] --> B["Adapter (e.g., Workers/Deno)"]
    B --> C["Hono.fetch(Request)"]
    C --> D["Response"]
    D --> E["Platform Response"]
```
Sources: [src/adapter/cloudflare-workers/websocket.ts:5-53](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-workers/websocket.ts#L5-L53), [src/adapter/deno/index.ts:6-9](https://github.com/blade47/hono/blob/main/src/adapter/deno/index.ts#L6-L9)

> [!NOTE]
> Edge adapters leverage `globalThis` to access native APIs, allowing them to remain performant without external dependencies.

## Node and Bun Adapters

Node and Bun adapters provide compatibility layers that translate standard Node.js server patterns (e.g., `IncomingMessage`, `ServerResponse`) into the Web Standard `Request` and `Response` lifecycle. While Node.js traditionally used callback-based streams, Hono's Node adapter bridges these via internal conversions, ensuring that streaming responses function seamlessly even when the runtime lacks native `ReadableStream` performance characteristics.

In environments like Bun, which natively supports many Web Standard APIs, the adapter is thinner, directly utilizing Bun's server capabilities while providing extensions for advanced features like built-in WebSockets or filesystem serving.

Sources: [src/adapter/bun/index.ts:6-11](https://github.com/blade47/hono/blob/main/src/adapter/bun/index.ts#L6-L11), [src/hono-base.ts:479-485](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L479-L485)

## Serverless Adapters

Serverless adapters, such as the AWS Lambda or Vercel adapters, handle complex event structures, including API Gateway v1/v2 proxy events, Application Load Balancers, and Lambda Function URLs. Because these environments do not provide a standard request flow, the adapters use an `EventProcessor` abstraction to normalize the diverse event payloads into a uniform `Request` object.

The AWS Lambda implementation uses a processor-pattern (e.g., `EventV1Processor`, `EventV2Processor`, `ALBProcessor`) to extract paths, headers, and query strings from varying event schemas. The logic for these processors is centralized in a dispatch mechanism that selects the appropriate processor based on structural characteristics of the input event.

```mermaid
classDiagram
    class EventProcessor {
        <<abstract>>
        +createRequest(event)
        +createResult(event, res)
        #getPath(event)
        #getMethod(event)
    }
    class EventV1Processor
    class EventV2Processor
    class ALBProcessor
    EventProcessor <|-- EventV1Processor
    EventProcessor <|-- EventV2Processor
    EventProcessor <|-- ALBProcessor
```
Sources: [src/adapter/aws-lambda/handler.ts:278-290](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L278-L290), [src/adapter/aws-lambda/handler.ts:639-651](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L639-L651)

> [!CAUTION]
> When handling binary payloads in Lambda, verify the `isContentTypeBinary` logic. The default implementation differentiates text and JSON-based content types from binary ones, but custom logic may be required for specific formats like images or PDFs.

## Event Dispatch Mechanism

The serverless adapter dispatch mechanism dynamically routes the raw `event` object to the correct processor. The lookup is non-trivial because AWS event signatures can overlap. The code uses `Object.hasOwn()` checks to identify the event origin, ensuring that the `EventProcessor` chosen is capable of handling the specific JSON structure provided by AWS.

```typescript
// Identifying the correct processor in AWS Lambda
export const getProcessor = (event: LambdaEvent): EventProcessor<LambdaEvent> => {
  if (isProxyEventALB(event)) {
    return albProcessor
  }
  if (isProxyEventV2(event)) {
    return v2Processor
  }
  if (isLatticeEventV2(event)) {
    return latticeV2Processor
  }
  return v1Processor
}
```
Sources: [src/adapter/aws-lambda/handler.ts:639-651](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L639-L651)

## Data Transformation Trade-offs

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| `EventProcessor` | Encapsulates provider-specific parsing | Increased class bloat |
| `Request` standardization | Unified handler API | Payload normalization overhead |
| `Response.arrayBuffer()` | Accurate binary detection | Memory usage for large responses |
| Headers conversion | Compatibility with Hono expectations | Iteration overhead on large headers |

Sources: [src/adapter/aws-lambda/handler.ts:318-342](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L318-L342), [src/adapter/aws-lambda/handler.ts:344-386](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L344-L386)

## Handler Implementation Example

The common pattern for all adapters is to initialize a `Hono` app and export a handler function. This example illustrates how a Lambda-based application is exported using the Hono adapter.

```javascript
import { Hono } from 'hono'
import { handle } from 'hono/aws-lambda'

const app = new Hono()

app.get('/', (c) => c.text('Hello from Lambda'))

// The exported handler is invoked by AWS Lambda at runtime
export const handler = handle(app)
```
Sources: [src/adapter/aws-lambda/handler.ts:211-222](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L211-L222)

---

## Security Headers

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/security-headers

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

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

- [src/middleware/secure-headers/secure-headers.ts](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts)
- [package.json](https://github.com/blade47/hono/blob/main/package.json)
- [src/middleware/csrf/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/csrf/index.ts)
- [src/middleware/etag/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/etag/index.ts)
- [src/middleware/cache/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/cache/index.ts)
- [src/middleware/method-override/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/method-override/index.ts)
- [src/adapter/aws-lambda/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts)
- [src/middleware/cors/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/cors/index.ts)
- [src/middleware/compress/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/compress/index.ts)
- [src/middleware/jwt/jwt.ts](https://github.com/blade47/hono/blob/main/src/middleware/jwt/jwt.ts)
- [src/context.ts](https://github.com/blade47/hono/blob/main/src/context.ts)
- [src/middleware/jwk/jwk.ts](https://github.com/blade47/hono/blob/main/src/middleware/jwk/jwk.ts)
- [src/middleware/etag/digest.ts](https://github.com/blade47/hono/blob/main/src/middleware/etag/digest.ts)
- [src/utils/cookie.ts](https://github.com/blade47/hono/blob/main/src/utils/cookie.ts)
- [jsr.json](https://github.com/blade47/hono/blob/main/jsr.json)
- [src/middleware/timing/timing.ts](https://github.com/blade47/hono/blob/main/src/middleware/timing/timing.ts)
- [src/jsx/intrinsic-element/components.ts](https://github.com/blade47/hono/blob/main/src/jsx/intrinsic-element/components.ts)
- [src/helper/proxy/index.ts](https://github.com/blade47/hono/blob/main/src/helper/proxy/index.ts)
- [src/helper/streaming/sse.ts](https://github.com/blade47/hono/blob/main/src/helper/streaming/sse.ts)
- [src/middleware/secure-headers/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/index.ts)
- [src/utils/headers.ts](https://github.com/blade47/hono/blob/main/src/utils/headers.ts)
- [src/middleware/bearer-auth/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/bearer-auth/index.ts)
- [src/utils/crypto.ts](https://github.com/blade47/hono/blob/main/src/utils/crypto.ts)
- [src/middleware/powered-by/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/powered-by/index.ts)
- [src/middleware/secure-headers/permissions-policy.ts](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/permissions-policy.ts)
- [src/utils/buffer.ts](https://github.com/blade47/hono/blob/main/src/utils/buffer.ts)
- [src/jsx/dom/intrinsic-element/components.ts](https://github.com/blade47/hono/blob/main/src/jsx/dom/intrinsic-element/components.ts)
</details>

The "Security Headers" subsystem in Hono is designed to enforce secure communication policies by automatically injecting standard HTTP security headers into outgoing server responses. It addresses common web vulnerabilities (such as XSS, clickjacking, and content sniffing) by providing a declarative middleware that ensures headers are set consistently across all routes or specific endpoints.

The design relies on a central middleware factory, `secureHeaders()`, which merges user-provided configuration with internal defaults. By operating within the middleware lifecycle, it guarantees that headers are applied after application logic execution, maintaining consistency regardless of route-specific response variations.

Beyond simple header injection, the system handles dynamic policy generation, including CSP (Content Security Policy) nonce management and Permissions-Policy parsing. It interacts closely with the Hono `Context` to store and retrieve nonces, facilitating seamless integration with template engines or frontend rendering helpers that need to reference these tokens for inline scripts.

## The `secureHeaders` Middleware Surface
The `secureHeaders` middleware serves as the primary entry point, accepting a `SecureHeadersOptions` object. It initializes by merging user-provided overrides, then filters headers based on the provided configuration. The middleware returns a handler that intercepts the request flow, executes necessary callbacks (such as dynamic CSP directive updates), and applies the finalized headers after the `await next()` call, ensuring that all headers are present in the response object before it reaches the client.

```typescript
const app = new Hono()
app.use(secureHeaders())
```
Sources: [src/middleware/secure-headers/secure-headers.ts:179-229](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts#L179-L229)

## Header Mapping and Filtering
The subsystem internally processes secure header configurations by mapping keys from `SecureHeadersOptions` to their corresponding HTTP header names and default values. During initialization, the middleware checks if a configuration key is present in the `SecureHeadersOptions` object, using internal mapping logic (`getFilteredHeaders`) to convert these into a list of `[string, string]` pairs, which are then applied to the response.

Sources: [src/middleware/secure-headers/secure-headers.ts:231-238](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts#L231-L238)

## Content Security Policy (CSP) Mechanism
The CSP mechanism is significantly more complex than standard headers because directives often require dynamic values (e.g., nonces). The `getCSPDirectives` function parses the `ContentSecurityPolicyOptions` object, identifying any directive values that are functions. These function-based values are replaced by placeholders, and their corresponding logic is registered as a callback. 

At request time, these callbacks are executed to generate the dynamic part of the directive (like a fresh random nonce), which is then injected into the final CSP string. This allows Hono to maintain the state of the nonces within the `Context` using the `secureHeadersNonce` key, ensuring that the same nonce is available to both the CSP header and the application rendering logic.

Sources: [src/middleware/secure-headers/secure-headers.ts:240-288](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts#L240-L288)

## Nonce Management
The `NONCE` export functions as a utility to handle nonce generation for CSP. When invoked, it retrieves or generates a 16-byte random nonce using the Web Crypto API, then stores it in the `Context`. This ensures that if the middleware is triggered during a template render, the same nonce is consistent throughout the request lifecycle.

```typescript
export const NONCE = (ctx: Context) => {
  const key = 'secureHeadersNonce'
  const init = ctx.get(key)
  const nonce = init || generateNonce()
  if (init == null) {
    ctx.set(key, nonce)
  }
  return `'nonce-${nonce}'`
}
```
Sources: [src/middleware/secure-headers/secure-headers.ts:137-145](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts#L137-L145)

> [!IMPORTANT]
> The `secureHeadersNonce` is stored in the `Context` variables. If developers add multiple custom CSP callbacks that depend on this nonce, they must ensure `secureHeaders()` is configured early in the middleware chain to ensure the `Context` is populated before rendering starts.

## Permissions Policy Formatting
Permissions-Policy directives are processed through `getPermissionsPolicyDirectives`, which transforms a camel-cased configuration object into the standard kebab-cased string format. 

1. **Directive Mapping**: Keys are processed via `camelToKebab` to ensure compatibility with standard browser specifications.
2. **Value Handling**:
   - `boolean`: Converted to `*` or `none`.
   - `Array`: If non-empty, values like `self` and `src` are kept literal, while other custom strings are quoted and enclosed in parentheses.
3. **Serialization**: The entire policy is joined by commas to form a valid HTTP `Permissions-Policy` header.

Sources: [src/middleware/secure-headers/secure-headers.ts:290-318](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/permissions-policy.ts#L290-L318)

## Execution Lifecycle and Header Application
The middleware follows a rigid order of operations to ensure correct header application:
1. **Header Preparation**: All static headers are filtered by options.
2. **Dynamic Directive Resolution**: CSP and other callbacks are reduced/executed.
3. **Middleware Chain**: `await next()` allows the rest of the application to run.
4. **Injection**: `setHeaders(ctx, headersToSet)` is called, finally applying the headers to the response object.
5. **Clean up**: If `removePoweredBy` is true, the `X-Powered-By` header is explicitly deleted from `ctx.res.headers`.

Sources: [src/middleware/secure-headers/secure-headers.ts:181-228](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts#L181-L228)

## Related

- [[Authentication Middleware]]
- [[Traffic Control]]


---

## Authentication Middleware

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/authentication-middleware

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

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

- [src/utils/jwt/jwt.ts](https://github.com/blade47/hono/blob/main/src/utils/jwt/jwt.ts)
- [src/middleware/secure-headers/secure-headers.ts](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts)
- [package.json](https://github.com/blade47/hono/blob/main/package.json)
- [src/middleware/jwk/jwk.ts](https://github.com/blade47/hono/blob/main/src/middleware/jwk/jwk.ts)
- [src/middleware/jwt/jwt.ts](https://github.com/blade47/hono/blob/main/src/middleware/jwt/jwt.ts)
- [src/middleware/bearer-auth/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/bearer-auth/index.ts)
- [src/hono-base.ts](https://github.com/blade47/hono/blob/main/src/hono-base.ts)
- [src/middleware/ip-restriction/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/ip-restriction/index.ts)
- [src/types.ts](https://github.com/blade47/hono/blob/main/src/types.ts)
</details>

Authentication middleware in Hono serves as the primary security layer for guarding routes, ensuring that incoming HTTP requests carry valid credentials before reaching the business logic. By leveraging standard Web Crypto APIs and JWT specifications, these components provide a robust, non-blocking flow that integrates seamlessly into the Hono middleware pipeline.

The architecture is designed to handle multiple common authentication patterns, including standard Bearer tokens, JSON Web Key (JWK) rotation through remote URI fetching, and static token validation. Because Hono is built on Web Standards, the middleware is platform-agnostic, running effectively across Cloudflare Workers, Node.js, Bun, and Deno, relying solely on the standard `crypto.subtle` API for cryptographic operations.

These components operate by inspecting headers or cookies, verifying claims against provided secrets or public keys, and either passing the request forward via `next()` or terminating execution early with an `HTTPException`. This ensures that downstream handlers only process requests that have satisfied the authentication invariant.

## JSON Web Token (JWT) Verification

The core of Hono's token-based authentication lies in the `Jwt` utility and its corresponding middleware. It provides high-level abstractions for signing and verifying tokens, adhering to [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519).

The `verify` function is the primary mechanism for token validation. It performs an ordered check:
1. **Header/Payload structure**: It ensures the token has exactly three parts (split by `.`).
2. **Algorithm enforcement**: It validates that the token's `alg` matches the expected algorithm, preventing "alg: none" or algorithm confusion attacks.
3. **Claim validation**: It checks `nbf` (Not Before), `exp` (Expiration), and `iat` (Issued At) against the current time.
4. **Signature verification**: It uses the Web Crypto `verifying` function to ensure the signature matches the signed header and payload.

> [!CAUTION]
> When using `verifyWithJwks`, the implementation enforces an explicit exclusion of symmetric algorithms (HS256/384/512) to prevent algorithm confusion attacks where a client might attempt to use a public key as a HMAC secret.

Sources: [src/utils/jwt/jwt.ts:96-188](https://github.com/blade47/hono/blob/main/src/utils/jwt/jwt.ts#L96-L188)

## JWK Auth Middleware

The `jwk` middleware extends the JWT functionality by supporting dynamic public key rotation, commonly required in OIDC-compliant identity providers.

When `jwks_uri` is provided, the middleware dynamically fetches the keyset. The mechanism involves:
1. Extracting the `kid` (Key ID) from the JWT header.
2. If `jwks_uri` is present, performing a `fetch` to retrieve the JSON Web Key Set.
3. Matching the `kid` from the token against the retrieved `keys` array.
4. If a match is found, executing the standard signature verification process.

```typescript
// Example: Using JWK middleware with a dynamic URI
app.use("/auth/*", jwk({
  jwks_uri: (c) => `https://${c.env.authServer}/.well-known/jwks.json`,
  alg: ['RS256']
}))
```
Sources: [src/middleware/jwk/jwk.ts:48-168](https://github.com/blade47/hono/blob/main/src/middleware/jwk/jwk.ts#L48-L168)

## Bearer Auth Middleware

The `bearerAuth` middleware provides a simplified, non-JWT-specific token validation mechanism. It is ideal for API key-based authentication where the token itself does not need a structured payload.

It supports two validation strategies:
1. **Static Tokens**: Validates against a string or array of strings.
2. **Dynamic Validation**: Uses a `verifyToken` function for custom logic (e.g., database lookup).

The security-critical component is the `timingSafeEqual` function, which prevents timing attacks by performing constant-time string comparison.

```typescript
// Example: Using bearer authentication with a static token
app.use('/api/*', bearerAuth({ token: 'my-secret-token' }))
```
Sources: [src/middleware/bearer-auth/index.ts:104-221](https://github.com/blade47/hono/blob/main/src/middleware/bearer-auth/index.ts#L104-L221)

## IP Restriction Middleware

The `ipRestriction` middleware provides infrastructure-level access control by inspecting the remote IP address of incoming requests.

**Mechanism:**
1. **Matching**: It accepts static IPs or CIDR notation (e.g., `10.0.0.0/8`).
2. **Registration**: The `buildMatcher` function compiles rules into `Set` structures for constant-time lookup and binary masks for CIDR ranges.
3. **Execution**: The IP is parsed and compared against the compiled rules. If a `denyList` rule matches, access is rejected. If an `allowList` is provided, the request must match at least one rule to proceed.

> [!NOTE]
> When `allowList` is provided, the middleware behaves as a whitelist-only filter. If the list is empty, it falls back to permissive behavior unless `denyList` rules trigger a block.

Sources: [src/middleware/ip-restriction/index.ts:51-167](https://github.com/blade47/hono/blob/main/src/middleware/ip-restriction/index.ts#L51-L167)

## Security Design Decisions

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| **Web Crypto API** | Platform-independent, secure native implementation | Less granular control over low-level crypto primitives |
| **Middleware Chaining** | Composable, allows layering (e.g., IP + JWT) | Higher stack depth for complex request pipelines |
| **Compile-time Matching** | Efficient IP restriction for high-traffic apps | Overhead during middleware initialization phase |
| **Typed Responses** | Improved type safety for error handling | Increased boilerplate for custom error responses |

Sources: [src/utils/jwt/jwt.ts](https://github.com/blade47/hono/blob/main/src/utils/jwt/jwt.ts), [src/middleware/ip-restriction/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/ip-restriction/index.ts)

## Request Flow Visualization

This diagram traces the standard authentication middleware sequence.

```mermaid
flowchart TD
    Req["Incoming Request"] --> Auth["Auth Middleware"]
    Auth --> Valid{Is Token/IP<br>Valid?}
    Valid -- No --> Err["401 Unauthorized<br>or 403 Forbidden"]
    Valid -- Yes --> Ctx["Set Auth Info<br>in c.jwtPayload"]
    Ctx --> Next["await next()"]
    Next --> Biz["Business Logic"]
```
Sources: [src/middleware/jwt/jwt.ts:76-158](https://github.com/blade47/hono/blob/main/src/middleware/jwt/jwt.ts#L76-L158), [src/middleware/ip-restriction/index.ts:238-279](https://github.com/blade47/hono/blob/main/src/middleware/ip-restriction/index.ts#L238-L279)

## Related

- [[Security Headers]]
- [[Cryptography and JWT]]


---

## Traffic Control

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/traffic-control

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

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

- [src/types.ts](https://github.com/blade47/hono/blob/main/src/types.ts)
- [src/adapter/aws-lambda/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts)
- [src/context.ts](https://github.com/blade47/hono/blob/main/src/context.ts)
- [src/hono-base.ts](https://github.com/blade47/hono/blob/main/src/hono-base.ts)
- [src/middleware/ip-restriction/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/ip-restriction/index.ts)
</details>

Traffic control in Hono is a layered responsibility distributed across its core router, middleware ecosystem, and platform-specific adapters. Fundamentally, it provides the mechanisms for routing requests to the appropriate handlers and enforcing access policies based on request attributes, such as remote IP addresses. By decoupling path-based dispatching from security-oriented traffic filters, Hono ensures that traffic control remains performant and extensible.

The system acts as a pipeline: incoming requests are intercepted by platform adapters (like those in `src/adapter/aws-lambda/handler.ts`), processed through path matching in the core `Hono` class, and potentially validated by middleware such as `ip-restriction` before reaching their final handlers. This modular design prevents complex security logic from bloating the core router, allowing developers to apply granular control where needed.

Traffic control logic within Hono prioritizes speed and type safety, leveraging TypeScript to ensure route definitions and schema outputs are validated at compile time. Whether managing binary content encoding in serverless environments or enforcing subnet-level access, Hono's traffic control mechanisms offer a robust foundation for building secure and scalable network applications.

## Request Dispatching and Routing

The core of traffic control is the routing mechanism implemented in the `Hono` class defined in `src/hono-base.ts`. The router dispatches incoming requests by matching the request method and path against a pre-registered tree of handlers. The `Hono` class maintains a `routes` array and a router instance, ensuring that path resolution is consistent across different environments.

Routing is driven by the `fetch` method, which initiates the processing logic that triggers path extraction, router matching, and finally the execution of the handler pipeline. This sequence processes the request flow:

1. `fetch()` → `this.getPath()` (extracts path) → `this.router.match()` (finds handlers)
2. `new Context()` (instantiates context with match results)
3. `compose()` (runs middleware and handler pipeline)
4. `c.res` (returns the result, finalizes the context)

The router performs a lookup based on `request.method` and `path`. The match result contains an ordered array of handler sets. The `compose()` function is then responsible for iterating through these handlers, ensuring that any middleware in the chain can control the flow by calling or skipping `next()`.

Sources: [src/hono-base.ts:406-466](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L406-L466), [src/hono-base.ts:479-485](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L479-L485)

## IP Restriction Middleware Mechanism

The `ip-restriction` middleware provides granular control over which clients can interact with specific routes or the entire application. It works by evaluating the remote IP address of a request against defined `denyList` and `allowList` rules before the main handler is executed.

The mechanism relies on `buildMatcher`, which pre-compiles IP rules into an efficient validator. Static IPs, CIDR blocks, and custom functions are normalized into a single function that checks the remote IP's binary representation.

> [!TIP]
> Pre-compiling rules in `buildMatcher` avoids re-parsing CIDR strings on every request, significantly optimizing performance during high traffic.

When a request arrives, the `ipRestriction` middleware retrieves the client IP address using the function passed as the first argument (such as `getConnInfo`). The evaluation order is strictly defined:
1. **Deny List:** If the IP matches any rule in `denyList`, the request is immediately rejected with a 403 Forbidden (or a custom error).
2. **Allow List:** If the IP matches any rule in `allowList`, the request proceeds to the next middleware or handler.
3. **Implicit Deny:** If an `allowList` is provided but no rules match, the request is denied.

Sources: [src/middleware/ip-restriction/index.ts:51-167](https://github.com/blade47/hono/blob/main/src/middleware/ip-restriction/index.ts#L51-L167), [src/middleware/ip-restriction/index.ts:218-278](https://github.com/blade47/hono/blob/main/src/middleware/ip-restriction/index.ts#L218-L278)

## Adapter-Level Traffic Transformation

Adapters like `aws-lambda` serve as the entry point for cloud traffic. They translate platform-specific event objects (e.g., `APIGatewayProxyEvent`) into standardized `Request` objects that Hono understands.

The various processor classes (such as `EventV1Processor`, `ALBProcessor`, and `EventV2Processor`) handle the translation of platform-specific headers and query parameters into a uniform `Request` object. Crucially, they handle traffic encoding—if `isContentTypeBinary` is true, the adapter base64-encodes the response body before returning it to the AWS Lambda runtime.

| Processor Class | Target Environment |
| :--- | :--- |
| `EventV1Processor` | API Gateway Proxy Events (v1) |
| `EventV2Processor` | API Gateway Proxy Events (v2) |
| `ALBProcessor` | Application Load Balancer Events |
| `LatticeV2Processor` | VPC Lattice Events (v2) |

Sources: [src/adapter/aws-lambda/handler.ts:278-402](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L278-L402), [src/adapter/aws-lambda/handler.ts:639-651](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L639-L651)

## Architecture and Design Trade-offs

The Hono architecture favors modularity over monolithic control structures. By using `compose`, the framework treats handlers, middleware, and error handlers as a unified pipeline.

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| Middlewares as functions | Highly composable, testable | Requires explicit `await next()` |
| Pre-compiled Matchers | High-speed traffic filtering | Initial overhead at startup |
| Adapter Pattern | Supports multiple cloud platforms | High complexity in adapter logic |

Sources: [src/hono-base.ts:406-466](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L406-L466), [src/middleware/ip-restriction/index.ts:51-167](https://github.com/blade47/hono/blob/main/src/middleware/ip-restriction/index.ts#L51-L167)

## Traffic Control Lifecycle

The following diagram illustrates how a request flows through the traffic control stack:

```mermaid
flowchart TD
    A[Incoming Request] --> B{Adapter}
    B -->|Convert Event| C[Hono fetch]
    C --> D[Middleware Chain]
    D --> E{Router}
    E --> F[Target Handler]
    F --> G[Response Object]
    G --> B
    B --> H[Platform Result]
```

Sources: [src/hono-base.ts:479-485](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L479-L485), [src/adapter/aws-lambda/handler.ts:252-276](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L252-L276)

## Implementation Example: IP Restriction

The following code demonstrates applying traffic control by restricting access to an `/admin` route using a custom IP list.

```typescript
import { Hono } from 'hono'
import { ipRestriction } from 'hono/ip-restriction'
import { getConnInfo } from 'hono/cloudflare-workers'

const app = new Hono()

// Apply IP restriction only to admin routes
app.use(
  '/admin/*',
  ipRestriction(getConnInfo, {
    allowList: ['203.0.113.0/24'], // Only allow this subnet
    denyList: ['203.0.113.5'],     // Specifically block one IP in that subnet
  })
)

app.get('/admin/dashboard', (c) => c.text('Welcome, Administrator'))
```

Sources: [src/middleware/ip-restriction/index.ts:188-216](https://github.com/blade47/hono/blob/main/src/middleware/ip-restriction/index.ts#L188-L216)

## Related

- [[Security Headers]]


---

## Utility Middleware

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/utility-middleware

<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/middleware/secure-headers/secure-headers.ts](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts)
- [src/adapter/aws-lambda/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts)
- [src/middleware/language/language.ts](https://github.com/blade47/hono/blob/main/src/middleware/language/language.ts)
- [src/types.ts](https://github.com/blade47/hono/blob/main/src/types.ts)
- [src/validator/validator.ts](https://github.com/blade47/hono/blob/main/src/validator/validator.ts)
</details>

Utility middleware in the Hono framework serves as the foundational layer for cross-cutting concerns, abstracting repetitive HTTP request/response tasks into composable, reusable units. By providing standardized implementations for security headers, request validation, language detection, and cloud platform adapters, these components allow developers to maintain clean, focused route handlers. This design follows the Hono principle of keeping the core framework "tiny" while offering powerful, optional functionality via a robust middleware pattern.

These components function by hooking into the Hono request-handling pipeline. Whether acting as a perimeter security layer (like `secureHeaders`), a data sanitization layer (`validator`), or a contextual enrichment layer (`languageDetector`), each utility effectively transforms the incoming `Context` or prepares the `Response` headers. This architecture ensures that platform-specific complexities—such as AWS Lambda event normalization or Content Security Policy generation—are handled uniformly, significantly reducing boilerplate code in business logic.

The utility subsystem leverages Hono's `Context` (`src/context.ts`) as a shared communication bus. Middleware can query request state, set internal variables via `ctx.set()`, and append headers before the request reaches the final handler. The flow is strictly ordered, enabling early-return scenarios (like the `validator` throwing an `HTTPException`) and late-stage modifications (like `secureHeaders` applying modifications to the `res` object after `next()` has finished).

## Request Validation Architecture

The `validator` subsystem provides a mechanism to verify incoming data against a target (e.g., `json`, `form`, `query`). It operates as a `MiddlewareHandler` that performs schema checks and data type enforcement before the application code is executed.

When a validator is defined, it maps a specific request target (e.g., `json`) to a validation function. If the content type check fails (e.g., the `Content-Type` header is not `application/json`), the middleware silently skips further validation for that target. However, if the data is present and correctly typed, the function processes the data.

> [!CAUTION]
> The `validator` throws an `HTTPException(400)` when it encounters malformed JSON or invalid FormData. If you are chaining multiple validators, ensure your error-handling middleware is configured to catch these status codes.

```typescript
// Example: Validating a JSON payload
app.post(
  '/user',
  validator('json', (value, c) => {
    if (!value.name) return c.json({ error: 'Name required' }, 400)
    return value
  }),
  (c) => c.json({ status: 'ok' })
)
```
Sources: [src/validator/validator.ts:46-138](https://github.com/blade47/hono/blob/main/src/validator/validator.ts#L46-L138)

## Security Headers Mechanism

The `secureHeaders` middleware enforces web security by injecting standard security headers (e.g., `Content-Security-Policy`, `X-Content-Type-Options`) into every response. The middleware initializes its state based on `DEFAULT_OPTIONS`, which are merged with any user-provided overrides.

A key feature is the dynamic generation of CSP nonces. The `NONCE` handler checks the current `Context` for an existing `secureHeadersNonce`. If absent, it generates a cryptographically secure random value using `crypto.getRandomValues(new Uint8Array(16))`, stores it in the context for reuse, and returns it. This ensures that the same nonce is available for both the CSP header and the HTML templates throughout the request lifecycle.

Sources: [src/middleware/secure-headers/secure-headers.ts:131-145](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts#L131-L145)

## Language Detection and Caching

The `languageDetector` middleware identifies the preferred locale of a client by iterating through a defined `order` of strategies: `querystring`, `cookie`, `header`, and `path`.

- **Detection Flow:** The `detectLanguage` function loops through the enabled detectors. As soon as one returns a non-null language string, it stops searching.
- **Normalization:** Every detection strategy passes the candidate string through `normalizeLanguage`, which compares it against `supportedLanguages`. It supports RFC 4647-style progressive truncation (e.g., matching `en-US` to `en`).
- **Caching:** If a language is successfully detected and caching is enabled (defaulting to `['cookie']`), the `cacheLanguage` function is called to set a persistent cookie on the response.

Sources: [src/middleware/language/language.ts:229-258](https://github.com/blade47/hono/blob/main/src/middleware/language/language.ts#L229-L258)

## Lambda Adapter Execution Flow

The `aws-lambda` adapter abstracts multiple AWS event sources (API Gateway v1/v2, ALB, Lattice) into a single, unified Hono `Request` object. The adapter uses a processor pattern to decouple platform-specific event normalization from the Hono application logic.

### Call-Chain: Handling an AWS Lambda Request
1. **`handle()`**: The entry point that captures the event and invokes `getProcessor(event)`.
2. **`processor.createRequest(event)`**: Normalizes query parameters, headers, and body (decoding base64 if needed).
3. **`app.fetch()`**: Executes the Hono app with the unified `Request` and cloud-platform context.
4. **`processor.createResult(event, res)`**: Transforms the standard `Response` back into the format expected by the specific AWS service (e.g., handling binary encoding).

Sources: [src/adapter/aws-lambda/handler.ts:239-276](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L239-L276)

## Platform Processor Selection

The `getProcessor` function acts as a factory, selecting the appropriate logic based on the shape of the incoming `LambdaEvent`.

| Processor | Triggered By | Logic Source |
| :--- | :--- | :--- |
| `albProcessor` | Application Load Balancer | `isProxyEventALB` |
| `v2Processor` | API Gateway v2 | `isProxyEventV2` |
| `latticeV2Processor` | VPC Lattice | `isLatticeEventV2` |
| `v1Processor` | API Gateway v1 | Fallback |

Sources: [src/adapter/aws-lambda/handler.ts:639-651](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L639-L651)

> [!NOTE]
> The factory prioritizes `ALB` and `V2` events specifically; if neither matches, it defaults to `v1Processor`. Ensure that the `isProxyEventALB` condition is unique for your infrastructure.

## Binary Content Detection

The adapter must decide whether to base64-encode the response body before returning it to AWS. This is handled by `defaultIsContentTypeBinary`, which returns `true` if the content type is not `text/plain`, `text/html`, etc.

```typescript
export const defaultIsContentTypeBinary = (contentType: string): boolean => {
  return !/^text\/(?:plain|html|css|javascript|csv)|(?:\/|\+)(?:json|xml)\s*(?:;|$)/.test(
    contentType
  )
}
```

Sources: [src/adapter/aws-lambda/handler.ts:677-681](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L677-L681)

## Design Trade-offs

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| **Processor Pattern** | Clean separation of cloud triggers | Requires maintaining multiple logic classes |
| **Context-based State** | Allows middleware to share data | Requires strict typing for `Variables` |
| **Normalization on-the-fly** | Consistent API for app developers | Slight CPU overhead per request |

Sources: [src/adapter/aws-lambda/handler.ts:278-402](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L278-L402)

## Related

- [[Traffic Control]]


---

## Schema Validation

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/schema-validation

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

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

- [src/adapter/aws-lambda/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts)
- [src/types.ts](https://github.com/blade47/hono/blob/main/src/types.ts)
- [src/middleware/secure-headers/secure-headers.ts](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts)
- [src/request.ts](https://github.com/blade47/hono/blob/main/src/request.ts)
- [src/hono-base.ts](https://github.com/blade47/hono/blob/main/src/hono-base.ts)
- [src/validator/validator.ts](https://github.com/blade47/hono/blob/main/src/validator/validator.ts)
</details>

Schema Validation is a core mechanism in Hono that enables declarative runtime verification of incoming request data. By coupling request targets (e.g., `json`, `query`, `param`) with user-defined validation functions, Hono ensures that downstream handlers receive processed and verified data. This architecture shifts the responsibility of data integrity from the business logic layer into a composable pipe, reducing boilerplate error handling code within routes.

The design centers on the `validator` function, which integrates with Hono’s request lifecycle. When a request hits a registered endpoint, the validator inspects the request, extracts data segments based on a specified target, and passes them to a validation function. If validation fails or the request payload is malformed, the validator terminates the request chain. Successful validation results are then attached to the `HonoRequest` instance, allowing handlers to access them via `c.req.valid()`.

This subsystem is tied to Hono’s type-safety system. By defining custom types for `Input`, developers can propagate validation outcomes through the application stack. This creates a contract-first development flow where the validation logic at the edge of the system dictates the signatures of request objects within the handler, ensuring robust data handling alongside validation.

## The Validator Mechanism

The `validator` function is a higher-order function that returns an asynchronous request handler. Its primary mechanism involves detecting the incoming request's `Content-Type`, extracting the requested data segment, and executing the provided validation function.

When `validator(target, validationFunc)` is invoked:
1. It returns an async function that intercepts the request processing chain.
2. Inside, it checks the `Content-Type` against regex patterns (like `jsonRegex` or `multipartRegex`) to ensure compatibility with the requested target.
3. If the type matches, it parses the body (e.g., using `c.req.json()` or by processing the request buffer into `FormData`).
4. The parsed value is passed to `validationFunc(value, c)`.
5. If the result from `validationFunc` is a `Response`, the validator short-circuits the pipeline. Otherwise, it invokes `c.req.addValidatedData(target, data)` to store the result.

Sources: [src/validator/validator.ts:46-150](https://github.com/blade47/hono/blob/main/src/validator/validator.ts#L46-L150)

## Supported Data Targets

The subsystem supports several predefined targets for data extraction, mapped internally to the structure of the incoming request:

*   **json**: Parses the request body as JSON.
*   **form**: Parses `multipart/form-data` or `x-www-form-urlencoded`.
*   **query**: Extracts data from URL query parameters.
*   **param**: Extracts path parameters from the routing context.
*   **header**: Extracts request headers.
*   **cookie**: Extracts browser cookies.

Sources: [src/validator/validator.ts:93-148](https://github.com/blade47/hono/blob/main/src/validator/validator.ts#L93-L148)

## Lifecycle Integration

Validation is a crucial step in the Hono request pipeline. By attaching data to the `HonoRequest` instance using `addValidatedData`, the system guarantees that when a handler eventually executes, it does not need to perform redundant parsing or type validation.

> [!TIP]
> Place the `validator` early in the execution chain to ensure that subsequent handlers receive clean, validated data and to prevent unnecessary processing if the input is malformed.

Sources: [src/request.ts:334-341](https://github.com/blade47/hono/blob/main/src/request.ts#L334-L341), [src/validator/validator.ts:89-148](https://github.com/blade47/hono/blob/main/src/validator/validator.ts#L89-L148)

## Error Handling and Invariants

The `validator` ensures strict adherence to the expected format. If a request claims to be `application/json` but contains invalid syntax, the validator catches the failure and throws an `HTTPException`.

```typescript
try {
  value = await c.req.json()
} catch {
  const message = 'Malformed JSON in request body'
  throw new HTTPException(400, { message })
}
```

This guard line is load-bearing; it ensures that the `validationFunc` is never invoked with unparseable data, maintaining the invariant that the input to the user's validation logic is always syntactically correct.

Sources: [src/validator/validator.ts:98-103](https://github.com/blade47/hono/blob/main/src/validator/validator.ts#L98-L103)

## Worked Example

This example demonstrates using the validator to process JSON input and enforce validation rules before the handler executes.

```typescript
import { Hono } from 'hono'
import { validator } from 'hono/validator'

const app = new Hono()

app.post(
  '/user',
  validator('json', (value, c) => {
    if (typeof value.name !== 'string') {
      return c.text('Invalid name', 400)
    }
    return value
  }),
  (c) => {
    const data = c.req.valid('json')
    return c.json({ message: `Hello ${data.name}` })
  }
)
```

Sources: [src/validator/validator.ts:46-88](https://github.com/blade47/hono/blob/main/src/validator/validator.ts#L46-L88)

## Design Trade-offs

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| Pipeline-based validation | Decouples validation from route logic. | Introduces middleware overhead per request. |
| Functional injection | Highly flexible; custom logic allowed. | Increased developer burden for manual checks. |
| In-place data storage | Memory efficient; no extra objects created. | Modifies request state; requires careful lifecycle management. |

Sources: [src/validator/validator.ts:89-148](https://github.com/blade47/hono/blob/main/src/validator/validator.ts#L89-L148)

## Related

- [[RPC Client]]


---

## RPC Client

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/rpc-client

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

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

- [src/types.ts](https://github.com/blade47/hono/blob/main/src/types.ts)
- [src/client/client.ts](https://github.com/blade47/hono/blob/main/src/client/client.ts)
- [src/request.ts](https://github.com/blade47/hono/blob/main/src/request.ts)
- [src/client/types.ts](https://github.com/blade47/hono/blob/main/src/client/types.ts)
- [package.json](https://github.com/blade47/hono/blob/main/package.json)
- [src/hono.ts](https://github.com/blade47/hono/blob/main/src/hono.ts)
- [src/hono-base.ts](https://github.com/blade47/hono/blob/main/src/hono-base.ts)
</details>

The Hono RPC Client is a type-safe interface generator that enables seamless communication between a frontend or client-side application and a Hono server. By leveraging TypeScript's inference capabilities, it maps the server's routing structure to a proxy object, effectively allowing developers to call server-side routes as if they were local functions.

The core philosophy of the RPC client is to eliminate the need for manual endpoint synchronization. Instead of writing `fetch` calls with string-based URLs, developers use the proxy interface generated by `hc` (Hono Client). This ensures that request parameters, body types, and response formats are strictly typed, reducing runtime errors and improving developer ergonomics.

Architecturally, the RPC client uses a JavaScript `Proxy` to intercept property access and method calls. This allows it to dynamically construct the request path based on the chain of property accesses (e.g., `client.users.posts[":id"].$get()`). The client then translates these calls into standard HTTP requests, providing a consistent API surface regardless of the underlying server-side complexity.

## Proxy Interception Mechanism

The RPC client relies on the `createProxy` function to build a chainable API surface. Every time a property is accessed on the client object, `createProxy` is called recursively, appending the key to a `path` array. This continues until a method is invoked, which triggers the `apply` trap of the proxy.

The mechanism uses a `Callback` function that captures the `path` and the `args` passed during the invocation. This callback acts as the entry point for determining how to handle the request — whether it's a standard HTTP fetch, a URL calculation, or a WebSocket connection.

```mermaid
flowchart LR
    A["Proxy (Client)"] -- .users.posts --> B["Proxy (Path: ['users', 'posts'])"]
    B -- .[":id"] --> C["Proxy (Path: ['users', 'posts', ':id'])"]
    C -- .$get() --> D["Callback (Path, Args)"]
```
Sources: [src/client/client.ts:15-31](https://github.com/blade47/hono/blob/main/src/client/client.ts#L15-L31)

## Request Execution Flow

When a user calls a method (e.g., `$get`), the callback creates an instance of `ClientRequestImpl`. This class is responsible for the actual network interaction. It transforms the provided `args` (including `json`, `query`, or `form`) into a standard `Request` object and executes the fetch request.

The request flow follows this chain:
1.  **Path Reconstruction:** The client joins the accumulated path array and merges it with the `baseUrl`.
2.  **Parameter Injection:** `replaceUrlParam` substitutes placeholders like `:id` with actual values from the arguments.
3.  **Search Params:** If query parameters are provided, they are converted to `URLSearchParams` and appended to the URL.
4.  **Body Serialization:** Depending on the input target (e.g., `args.json`), the body is stringified and the `Content-Type` header is set to `application/json`.

Sources: [src/client/client.ts:33-130](https://github.com/blade47/hono/blob/main/src/client/client.ts#L33-L130)

## WebSocket Integration

The RPC client handles WebSocket connections via the `$ws` endpoint. When invoked, it translates the path into a WebSocket URL (replacing `http` with `ws` protocol). It optionally serializes query parameters into the URL search string.

The `establishWebSocket` helper allows for custom WebSocket implementations, defaulting to the native browser `WebSocket`. The client ensures that any provided path parameters are replaced before the connection is established.

Sources: [src/client/client.ts:187-212](https://github.com/blade47/hono/blob/main/src/client/client.ts#L187-L212)

## Configuration and Options

The `ClientRequestOptions` type provides granular control over how the RPC client communicates with the server. It allows users to define custom `fetch` functions (useful for testing or proxying) and headers that are added to every request.

| Option | Type | Purpose |
| :--- | :--- | :--- |
| `fetch` | `typeof fetch` | Custom fetch function to execute requests. |
| `headers` | `Record | function` | Headers to include in the request. |
| `init` | `RequestInit` | Standard `RequestInit` configuration. |
| `buildSearchParams` | `BuildSearchParamsFn` | Strategy for query parameter serialization. |

Sources: [src/client/types.ts:32-65](https://github.com/blade47/hono/blob/main/src/client/types.ts#L32-L65)

> [!NOTE]
> When providing custom `init` options, exercise caution: these take the highest priority and can overwrite critical Hono-managed properties like `method`, `body`, or `headers`.

## Practical Usage Example

The following example demonstrates how to initialize the RPC client and use it to call an API endpoint.

```typescript
import { hc } from 'hono/client'
import type { AppType } from './server' // Imported from the server

const client = hc<AppType>('https://api.example.com')

// Calling an endpoint: GET /users/:id
const res = await client.users[':id'].$get({
  param: { id: '123' },
  query: { details: 'true' }
})

if (res.ok) {
  const data = await res.json()
  console.log(data)
}
```
Sources: [src/client/client.ts:133-224](https://github.com/blade47/hono/blob/main/src/client/client.ts#L133-L224)

## Design Trade-offs

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| `Proxy` object | Allows clean, natural JS/TS syntax for API calls. | Can hide complexity, making debugging through chains difficult. |
| Type inference via `hc` | Zero manual API schema management. | Increases reliance on build-time TypeScript compilation. |
| `ClientRequestImpl` isolation | Encapsulates logic for path/body construction. | Creates a secondary layer between the proxy callback and native `fetch`. |

Sources: [src/client/client.ts](https://github.com/blade47/hono/blob/main/src/client/client.ts)

## Related

- [[Schema Validation]]


---

## Static Generation

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/static-generation

<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/helper/ssg/ssg.ts](https://github.com/blade47/hono/blob/main/src/helper/ssg/ssg.ts)
- [src/hono-base.ts](https://github.com/blade47/hono/blob/main/src/hono-base.ts)
- [src/adapter/cloudflare-pages/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/handler.ts)
- [src/preset/quick.ts](https://github.com/blade47/hono/blob/main/src/preset/quick.ts)
- [src/helper/ssg/utils.ts](https://github.com/blade47/hono/blob/main/src/helper/ssg/utils.ts)
- [src/hono.ts](https://github.com/blade47/hono/blob/main/src/hono.ts)
- [src/router/reg-exp-router/prepared-router.ts](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/prepared-router.ts)
- [src/helper/route/index.ts](https://github.com/blade47/hono/blob/main/src/helper/route/index.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)
- [jsr.json](https://github.com/blade47/hono/blob/main/jsr.json)
- [src/helper/ssg/plugins.ts](https://github.com/blade47/hono/blob/main/src/helper/ssg/plugins.ts)
- [src/helper/dev/index.ts](https://github.com/blade47/hono/blob/main/src/helper/dev/index.ts)
- [src/helper/ssg/middleware.ts](https://github.com/blade47/hono/blob/main/src/helper/ssg/middleware.ts)
- [src/helper/ssg/index.ts](https://github.com/blade47/hono/blob/main/src/helper/ssg/index.ts)
- [src/router/linear-router/router.ts](https://github.com/blade47/hono/blob/main/src/router/linear-router/router.ts)
- [src/preset/tiny.ts](https://github.com/blade47/hono/blob/main/src/preset/tiny.ts)
- [src/adapter/deno/ssg.ts](https://github.com/blade47/hono/blob/main/src/adapter/deno/ssg.ts)
- [src/adapter/bun/ssg.ts](https://github.com/blade47/hono/blob/main/src/adapter/bun/ssg.ts)
- [src/middleware/serve-static/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/serve-static/index.ts)
- [src/router/reg-exp-router/index.ts](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/index.ts)
- [perf-measures/type-check/scripts/generate-app.ts](https://github.com/blade47/hono/blob/main/perf-measures/type-check/scripts/generate-app.ts)
- [src/router/smart-router/index.ts](https://github.com/blade47/hono/blob/main/src/router/smart-router/index.ts)
- [src/router/reg-exp-router/trie.ts](https://github.com/blade47/hono/blob/main/src/router/reg-exp-router/trie.ts)
- [src/adapter/deno/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/deno/index.ts)
- [src/router/pattern-router/index.ts](https://github.com/blade47/hono/blob/main/src/router/pattern-router/index.ts)
- [src/router/trie-router/index.ts](https://github.com/blade47/hono/blob/main/src/router/trie-router/index.ts)
- [src/router/linear-router/index.ts](https://github.com/blade47/hono/blob/main/src/router/linear-router/index.ts)
- [src/adapter/bun/index.ts](https://github.com/blade47/hono/blob/main/src/adapter/bun/index.ts)
</details>

Static Generation (SSG) in Hono enables pre-rendering routes into static files during the build process, significantly improving performance by serving assets directly from the file system rather than invoking the application logic at runtime. This subsystem is designed to crawl the application's defined routes, execute them, and persist their outputs to a specified directory.

By abstracting the file system interface through `FileSystemModule`, Hono's SSG mechanism remains environment-agnostic, allowing seamless integration with different runtimes like Node.js, Deno, or Bun. This flexibility ensures that the SSG workflow is consistent across various platforms while leveraging environment-specific optimized file writing routines.

The architecture emphasizes composability and extensibility via plugin support. This allows developers to intercept the request lifecycle, handle dynamic routing parameters, or modify generated responses to suit specific requirements, such as handling redirects or content transformations.

## The Generation Lifecycle

The SSG process coordinates route discovery, execution, and persistence. It starts by filtering routes to identify eligible static content, then proceeds through the SSG plugins to collect content and save it to the disk.

```mermaid
flowchart TD
    A["Hono App"] --> B["toSSG"]
    B --> C{SSG Plugins}
    C -->|Hook Execution| D["app.request (Internal)"]
    D --> E["parseResponseContent"]
    E --> F["saveContentToFile"]
    F --> G["fsModule"]
```

Sources: [src/helper/ssg/ssg.ts:368-470](https://github.com/blade47/hono/blob/main/src/helper/ssg/ssg.ts#L368-L470), [src/helper/ssg/ssg.ts:310-334](https://github.com/blade47/hono/blob/main/src/helper/ssg/ssg.ts#L310-L334)

## File System Abstraction

The system requires an implementation of `FileSystemModule` to perform I/O operations. This decoupling allows the core logic to avoid runtime-specific dependencies, ensuring the same `toSSG` function works across diverse environments.

```typescript
export interface FileSystemModule {
  writeFile(path: string, data: string | Uint8Array): Promise<void>
  mkdir(path: string, options: { recursive: boolean }): Promise<void | string>
}
```

Implementations are provided for specific adapters:
- **Bun**: Configured via the export module in `src/adapter/bun/ssg.ts`.
- **Deno**: Configured via the export module in `src/adapter/deno/ssg.ts`.

Sources: [src/helper/ssg/ssg.ts:34-37](https://github.com/blade47/hono/blob/main/src/helper/ssg/ssg.ts#L34-L37), [src/adapter/bun/ssg.ts:13-18](https://github.com/blade47/hono/blob/main/src/adapter/bun/ssg.ts#L13-L18), [src/adapter/deno/ssg.ts:9-18](https://github.com/blade47/hono/blob/main/src/adapter/deno/ssg.ts#L9-L18)

## Dynamic Routing and Parameter Injection

For routes containing dynamic parameters, Hono uses the `ssgParams` middleware to inform the generator which specific paths to pre-render. When the generator encounters a route identified by `isDynamicRoute`, it expects the application to provide context via `ssgParams`.

> [!IMPORTANT]
> The `ssgParams` middleware effectively "short-circuits" the request processing for those routes in the generator's context, preventing unnecessary handler execution while collecting the required parameters for static rendering.

```typescript
export const ssgParams: SSGParamsMiddleware = (params) => async (c, next) => {
  if (isDynamicRoute(c.req.path)) {
    (c.req.raw as AddedSSGDataRequest).ssgParams = Array.isArray(params) ? params : await params(c)
    return c.notFound() 
  }
  await next()
}
```

Sources: [src/helper/ssg/middleware.ts:43-49](https://github.com/blade47/hono/blob/main/src/helper/ssg/middleware.ts#L43-L49), [src/helper/ssg/utils.ts:73-75](https://github.com/blade47/hono/blob/main/src/helper/ssg/utils.ts#L73-L75)

## Plugin System

Plugins allow customization of the SSG process. By bundling hooks, plugins can easily inject logic before a request is sent, after a response is received, or after the generation process completes.

| Hook Type | Trigger Point | Purpose |
| :--- | :--- | :--- |
| `beforeRequestHook` | Before sending the request | Request modification or filtering |
| `afterResponseHook` | After the response is received | Response processing, status check, or redirect generation |
| `afterGenerateHook` | After file writing | Cleanup or reporting |

Sources: [src/helper/ssg/ssg.ts:175-179](https://github.com/blade47/hono/blob/main/src/helper/ssg/ssg.ts#L175-L179), [src/helper/ssg/plugins.ts:11-20](https://github.com/blade47/hono/blob/main/src/helper/ssg/plugins.ts#L11-L20)

## Path Resolution and Sanitization

The `generateFilePath` function transforms route paths into valid file system paths, applying directory and extension logic. It guarantees that generated files are contained within the `outDir` to prevent potential path traversal vulnerabilities.

> [!CAUTION]
> The `ensureWithinOutDir` check is a security invariant that throws an error if a computed `filePath` escapes the `outDir`. This is critical for preventing arbitrary file system writes during the generation phase.

Sources: [src/helper/ssg/ssg.ts:50-71](https://github.com/blade47/hono/blob/main/src/helper/ssg/ssg.ts#L50-L71), [src/helper/ssg/utils.ts:77-87](https://github.com/blade47/hono/blob/main/src/helper/ssg/utils.ts#L77-L87)

## Execution Walkthrough: `toSSG`

The `toSSG` orchestrator follows this sequence:

1. **Initialization**: Normalizes hooks from the provided `plugins` array.
2. **Setup**: Configures internal utilities for routing and hook execution.
3. **Execution**: Iterates through route paths, resolving parameters via `ssgParams`.
4. **Processing**: Triggers internal app requests for each parameter set.
5. **Persistence**: `saveContentToFile` creates the necessary directories recursively and writes the data to the `outputDir` using the injected `fsModule`.
6. **Finalization**: Executes `afterGenerateHook` callbacks after the main operations conclude.

Sources: [src/helper/ssg/ssg.ts:368-470](https://github.com/blade47/hono/blob/main/src/helper/ssg/ssg.ts#L368-L470)

## Related

- [[JSX Renderer]]


---

## Testing Utilities

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/testing-utilities

<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/client/client.ts](https://github.com/blade47/hono/blob/main/src/client/client.ts)
- [src/types.ts](https://github.com/blade47/hono/blob/main/src/types.ts)
- [src/context.ts](https://github.com/blade47/hono/blob/main/src/context.ts)
- [src/hono-base.ts](https://github.com/blade47/hono/blob/main/src/hono-base.ts)
</details>

Testing utilities in Hono are designed to bridge the gap between development and production environments, providing a seamless way to simulate network requests and verify application behavior without needing to spin up an actual HTTP server. By leveraging the Web Standards-compliant nature of Hono, these utilities allow developers to pass a `Request` or a URL string directly into an application instance, returning a standard `Response` object. This approach ensures that tests are fast, isolated, and reflect the exact logic execution path that a real production request would follow.

The core of this system is centered on the `request` method exposed by the `Hono` class. This method abstracts the complexities of request creation and dispatching, handling the conversion of simplified inputs (like path strings) into full-fledged `Request` objects. By integrating deeply with the framework's routing and dispatch mechanisms, these utilities allow for full-stack integration testing, ensuring that middleware, route matching, and error handling all perform as expected during development.

## The `request` Method Mechanism

The `request` utility serves as the primary gateway for unit and integration testing. Its mechanism transforms simple input parameters into a fully qualified `Request` object and dispatches it to the application's internal `#dispatch` flow.

1. **Input Normalization:** If the input is a `string` or `URL`, the method ensures it is rooted correctly using `mergePath` and defaults to a `http://localhost` origin if no host is specified.
2. **Request Construction:** It initializes a standard `Request` object using the normalized URL and provided `RequestInit` parameters.
3. **Dispatch:** It triggers the `fetch` method, which is the internal entry point that performs route matching, middleware composition, and final response execution.

```typescript
// Testing an endpoint:
test('GET /hello is ok', async () => {
  const res = await app.request('/hello')
  expect(res.status).toBe(200)
})
```
Sources: [src/hono-base.ts:499-517](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L499-L517)

## Dispatching the Request

The execution flow for an `app.request()` call eventually reaches `#dispatch` inside `src/hono-base.ts`. This is the core logic engine of the framework.

- **Request Routing:** The method utilizes the `router` to match the incoming `method` and `path` (derived via `getPath`).
- **Context Initialization:** A `Context` object is instantiated, encapsulating the `Request`, the router's `matchResult`, and optional environment bindings (`env`) or execution contexts.
- **Composition Execution:** The framework uses the `compose` utility to execute the middleware chain. This involves iterating through the handlers matched by the router and managing the `next()` calls.
- **Finalization Guard:** A strict invariant exists: if the composition finishes but the `Context` object remains in a non-finalized state, an error is thrown. This forces developers to ensure that every path results in a `Response` being returned.

> [!IMPORTANT]
> A `Context` must be finalized before the dispatch cycle concludes. If a `Response` is not explicitly set or returned, the system treats it as an error-prone state, preventing silent failures.

Sources: [src/hono-base.ts:406-466](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L406-L466)

## Simulated Web Workers and Adapters

Hono's testing utilities account for the serverless environments the framework targets (e.g., Cloudflare Workers). The `#dispatch` method accepts an `executionCtx`, which provides mock implementations for methods like `waitUntil` and `passThroughOnException`.

When running in environments like Vitest or Deno, the `request` method behaves exactly as it would in production by providing a standard environment object that conforms to the `ExecutionContext` interface. This allows testing middleware that interacts with async background tasks (using `c.executionCtx.waitUntil`) without breaking the test runner.

Sources: [src/context.ts:31-52](https://github.com/blade47/hono/blob/main/src/context.ts#L31-L52), [src/hono-base.ts:407-408](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L407-L408)

## Error Handling and Debugging

The testing utilities inherit the global error handling configuration of the Hono application instance. If an error is caught during the dispatch process—whether from a handler throwing an exception or an unfinalized context—the `errorHandler` is invoked.

The error handler itself is designed to handle `HTTPResponseError` specifically. If an error contains a `getResponse` method, the test will correctly capture the intended response object rather than a generic "Internal Server Error." This is vital for testing custom API error formats or authentication failures.

```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-42](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L35-L42)

## Typed Client Testing

Beyond server-side testing, Hono provides `hc` (Hono Client) for type-safe interaction. Testing the client involves creating a proxy that can be called with specific API paths. This utility uses `createProxy` internally to build path hierarchies. 

When testing the client, you can pass a custom `fetch` implementation into the `ClientRequestOptions`. This is an essential pattern for testing the client against mock services (like MSW - Mock Service Worker). By supplying `opt.fetch`, you can redirect all client calls to a sandboxed fetch environment.

```typescript
// Passing a custom fetch for MSW/Node-fetch testing
const res = await hc('/api', { fetch: myMockFetch }).user.$get()
```
Sources: [src/client/client.ts:133-224](https://github.com/blade47/hono/blob/main/src/client/client.ts#L133-L224)

## Design Trade-offs

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| `app.request` wrapping `fetch` | Standard Web APIs; familiar usage | Requires URL normalization |
| In-memory dispatch | Extremely fast execution | Bypasses actual network layer |
| `compose` middleware chain | Predictable order of operations | Complex async stack trace management |

Sources: [src/hono-base.ts:499-517](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L499-L517)

## Worked Example: Integration Test

This example shows how to perform a full integration test on an app instance, exercising route matching, context modification, and final response validation.

```typescript
import { Hono } from './hono'

const app = new Hono()

app.use('*', async (c, next) => {
  c.set('user', 'admin')
  await next()
})

app.get('/hello', (c) => {
  return c.json({ user: c.get('user') })
})

// Integration Test
test('GET /hello works and reflects middleware state', async () => {
  const res = await app.request('/hello')
  const data = await res.json()
  
  expect(res.status).toBe(200)
  expect(data.user).toBe('admin')
})
```
Sources: [src/hono-base.ts:499-517](https://github.com/blade47/hono/blob/main/src/hono-base.ts#L499-L517), [src/context.ts:546-556](https://github.com/blade47/hono/blob/main/src/context.ts#L546-L556)

## Related

- [[Quick Start]]


---

## Cookie Handling

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/cookie-handling

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

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

- [src/utils/jwt/jwt.ts](https://github.com/blade47/hono/blob/main/src/utils/jwt/jwt.ts)
- [src/middleware/secure-headers/secure-headers.ts](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts)
- [src/adapter/aws-lambda/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts)
- [src/client/client.ts](https://github.com/blade47/hono/blob/main/src/client/client.ts)
- [src/context.ts](https://github.com/blade47/hono/blob/main/src/context.ts)
- [src/utils/cookie.ts](https://github.com/blade47/hono/blob/main/src/utils/cookie.ts)
- [src/middleware/jwt/jwt.ts](https://github.com/blade47/hono/blob/main/src/middleware/jwt/jwt.ts)
- [src/middleware/jwk/jwk.ts](https://github.com/blade47/hono/blob/main/src/middleware/jwk/jwk.ts)
- [src/middleware/bearer-auth/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/bearer-auth/index.ts)
- [src/middleware/csrf/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/csrf/index.ts)
- [src/middleware/language/language.ts](https://github.com/blade47/hono/blob/main/src/middleware/language/language.ts)
- [src/hono.ts](https://github.com/blade47/hono/blob/main/src/hono.ts)
- [src/helper/cookie/index.ts](https://github.com/blade47/hono/blob/main/src/helper/cookie/index.ts)
- [src/request.ts](https://github.com/blade47/hono/blob/main/src/request.ts)
- [src/utils/jwt/jws.ts](https://github.com/blade47/hono/blob/main/src/utils/jwt/jws.ts)
- [src/middleware/jwk/keys.test.json](https://github.com/blade47/hono/blob/main/src/middleware/jwk/keys.test.json)
- [src/adapter/lambda-edge/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/lambda-edge/handler.ts)
- [src/middleware/cors/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/cors/index.ts)
- [package.json](https://github.com/blade47/hono/blob/main/src/package.json)
- [src/client/fetch-result-please.ts](https://github.com/blade47/hono/blob/main/src/client/fetch-result-please.ts)
- [src/types.ts](https://github.com/blade47/hono/blob/main/src/types.ts)
</details>

Cookie handling in Hono is designed around web standards, providing a unified mechanism for parsing, serializing, and securing HTTP cookies across diverse serverless environments. By abstracting the complexities of the `Set-Cookie` header and cookie parsing, it allows developers to manage stateful interactions without worrying about low-level string manipulation or RFC-compliant parsing.

At its core, the subsystem balances ease of use with robust security requirements. It handles standard cookie parsing while offering specialized utilities for signed cookies, which ensure data integrity via HMAC-SHA256 signatures. This ensures that cookie values can be verified on the server side to detect tampering, a critical requirement for session and authentication management.

The architecture is built to be environment-agnostic. Because Hono aims to run on platforms ranging from Cloudflare Workers to AWS Lambda, the cookie utilities rely on the standard Web Crypto API (`crypto.subtle`) for signing operations and standard header management for persistence. This ensures that high-level abstractions remain performant and compliant with the security expectations of modern web applications.

## Parsing Mechanisms

The core parsing logic is implemented in `src/utils/cookie.ts`. The `parse` function handles incoming `Cookie` headers by splitting the string on semicolons and processing each key-value pair.

A key design choice here is the use of a "fast-path" for lookups. If a `name` is provided to `parse`, the implementation checks for its existence before fully iterating over the pairs, returning an empty object if the target key is absent.

```typescript
// Fast-path: return immediately if the demanded-key is not in the cookie string
if (name && cookie.indexOf(name) === -1) {
  return {}
}
```
Sources: [src/utils/cookie.ts:103-106](https://github.com/blade47/hono/blob/main/src/utils/cookie.ts#L103-L106)

Validation is strict. The code enforces name validity through a regular expression that checks for alphanumeric and specific special characters, and value validation via a regex that restricts characters to the ASCII range 32-126 (excluding forbidden ones like double quotes).

> [!TIP]
> The parser automatically unquotes values if they are enclosed in double quotes, providing seamless compatibility with varied client implementations.

Sources: [src/utils/cookie.ts:125-127](https://github.com/blade47/hono/blob/main/src/utils/cookie.ts#L125-L127)

## Serialization and Signing

Cookie serialization is handled by `_serialize`, which constructs the header string based on the provided `CookieOptions`. This includes attributes such as `Domain`, `Path`, `Max-Age`, and `Secure`.

To prevent tampering, `serializeSigned` (and `parseSigned`) facilitates HMAC-based signing. The mechanism:
1. Derives a `CryptoKey` using `crypto.subtle.importKey` with the HMAC SHA-256 algorithm.
2. Generates a base64 signature of the value.
3. Appends this signature to the value, separated by a dot (`value.signature`).

```typescript
const makeSignature = async (value: string, secret: string | BufferSource): Promise<string> => {
  const key = await getCryptoKey(secret)
  const signature = await crypto.subtle.sign(algorithm.name, key, new TextEncoder().encode(value))
  return btoa(String.fromCharCode(...new Uint8Array(signature)))
}
```
Sources: [src/utils/cookie.ts:44-49](https://github.com/blade47/hono/blob/main/src/utils/cookie.ts#L44-L49)

## Security and Prefix Enforcement

The system enforces RFC 6265bis recommendations for cookie prefixes, specifically `__Secure-` and `__Host-`. The `_serialize` function contains explicit guards to ensure these attributes are handled correctly.

| Prefix | Required Constraint |
| :--- | :--- |
| `__Secure-` | Must have the `Secure` attribute. |
| `__Host-` | Must have `Secure`, `Path='/'`, and no `Domain` attribute. |

If these invariants are not met, the code throws an explicit `Error`, preventing the creation of insecure cookies in sensitive contexts.

```typescript
if (name.startsWith('__Host-')) {
  if (!opt.secure) {
    throw new Error('__Host- Cookie must have Secure attributes')
  }
  // ... check path and domain
}
```
Sources: [src/utils/cookie.ts:179-192](https://github.com/blade47/hono/blob/main/src/utils/cookie.ts#L179-L192)

## Adapter-Level Integration

Different serverless adapters need different ways to set and get cookies. For example, AWS Lambda provides cookies in an event object for V2, while ALB might use `multiValueHeaders`. The `adapter/aws-lambda` implementation provides a `setCookies` mechanism that detects if `getSetCookie()` is available on the `Headers` object.

```typescript
this.setCookies(_event: E, res: Response, result: APIGatewayProxyResult) {
  if (res.headers.has('set-cookie')) {
    const cookies = res.headers.getSetCookie
      ? res.headers.getSetCookie()
      : Array.from(res.headers.entries())
          .filter(([k]) => k === 'set-cookie')
          .map(([, v]) => v)
    // ...
  }
}
```
Sources: [src/adapter/aws-lambda/handler.ts:388-401](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts#L388-L401)

This ensures that regardless of whether the platform supports the standard `getSetCookie()` API (common in modern runtimes), the handler can extract multiple cookies accurately.

## Helper API Surface

The `helper/cookie` module acts as the public-facing API for Hono applications. It provides high-level methods to interact with the `Context`.

```typescript
import { setCookie, getCookie } from 'hono/cookie'

app.get('/set', (c) => {
  setCookie(c, 'flavor', 'chocolate', { httpOnly: true, secure: true })
  return c.text('cookie set')
})
```
Sources: [src/helper/cookie/index.ts:99-102](https://github.com/blade47/hono/blob/main/src/helper/cookie/index.ts#L99-L102)

The helper layer handles the injection of the `Set-Cookie` header into the response, using `{ append: true }` to ensure multiple cookies can be set in a single response cycle.

## Design Trade-offs

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| **HMAC-SHA256 Signing** | Prevents client-side manipulation of cookie data. | Adds overhead to read/write operations (crypto latency). |
| **Strict Regex Enforcement** | High security by rejecting malformed cookie names/values. | May reject legacy cookies with unusual characters. |
| **Web Crypto Dependency** | Portability across modern serverless runtimes. | Requires async interfaces for `getSignedCookie`. |

Sources: [src/utils/cookie.ts:37-66](https://github.com/blade47/hono/blob/main/src/utils/cookie.ts#L37-L66), [src/utils/cookie.ts:70-77](https://github.com/blade47/hono/blob/main/src/utils/cookie.ts#L70-L77)

## Related

- [[Context Execution]]


---

## Cryptography and JWT

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/cryptography-and-jwt

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

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

- [src/utils/jwt/jwt.ts](https://github.com/blade47/hono/blob/main/src/utils/jwt/jwt.ts)
- [src/middleware/secure-headers/secure-headers.ts](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts)
- [src/adapter/aws-lambda/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts)
- [package.json](https://github.com/blade47/hono/blob/main/package.json)
- [src/middleware/jwt/jwt.ts](https://github.com/blade47/hono/blob/main/src/middleware/jwt/jwt.ts)
- [src/middleware/jwk/jwk.ts](https://github.com/blade47/hono/blob/main/src/middleware/jwk/jwk.ts)
- [src/middleware/bearer-auth/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/bearer-auth/index.ts)
- [src/utils/jwt/jws.ts](https://github.com/blade47/hono/blob/main/src/utils/jwt/jws.ts)
- [src/middleware/jwk/keys.test.json](https://github.com/blade47/hono/blob/main/src/middleware/jwk/keys.test.json)
- [src/hono.ts](https://github.com/blade47/hono/blob/main/src/hono.ts)
- [src/context.ts](https://github.com/blade47/hono/blob/main/src/context.ts)
- [src/preset/quick.ts](https://github.com/blade47/hono/blob/main/src/preset/quick.ts)
- [src/middleware/csrf/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/csrf/index.ts)
- [src/hono-base.ts](https://github.com/blade47/hono/blob/main/src/hono-base.ts)
- [src/adapter/lambda-edge/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/lambda-edge/handler.ts)
- [src/utils/crypto.ts](https://github.com/blade47/hono/blob/main/src/utils/crypto.ts)
- [src/utils/jwt/types.ts](https://github.com/blade47/hono/blob/main/src/utils/jwt/types.ts)
- [src/middleware/basic-auth/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/basic-auth/index.ts)
- [src/utils/jwt/jwa.ts](https://github.com/blade47/hono/blob/main/src/utils/jwt/jwa.ts)
- [src/utils/jwt/index.ts](https://github.com/blade47/hono/blob/main/src/utils/jwt/index.ts)
- [src/middleware/jwt/index.ts](https://github.com/blade47/hono/blob/main/src/middleware/jwt/index.ts)
- [src/jsx/jsx-runtime.ts](https://github.com/blade47/hono/blob/main/src/jsx/jsx-runtime.ts)
- [src/utils/cookie.ts](https://github.com/blade47/hono/blob/main/src/utils/cookie.ts)
- [src/helper/cookie/index.ts](https://github.com/blade47/hono/blob/main/src/helper/cookie/index.ts)
- [src/request.ts](https://github.com/blade47/hono/blob/main/src/request.ts)
</details>

Cryptography and JWT form a critical security layer within the Hono framework, providing robust mechanisms for identity verification, data integrity, and secure transport state management. The architecture decouples cryptographic primitives from high-level authentication middleware, allowing developers to sign, verify, and decode JSON Web Tokens (JWT) while leveraging the underlying Web Crypto API. This approach ensures Hono remains compliant with modern web standards while remaining runtime-agnostic.

The subsystem addresses common security challenges such as algorithm confusion attacks, token expiration, and unauthorized access. By providing dedicated middleware like `jwt()` and `jwk()`, Hono simplifies the implementation of stateless authentication. These components maintain a clean separation between the cryptographic operations—handled in `jws.ts`—and the routing/request handling logic, ensuring that sensitive token validation logic remains centralized and testable.

Integration with adjacent components is seamless, particularly regarding request context and headers. The `secure-headers` middleware works in tandem with these security modules to prevent vulnerabilities like CSRF or content-injection, while the `cookie` helpers offer cryptographically signed cookies to extend the lifecycle of authentication states. By prioritizing standard-compliant implementations of RFC 7515 (JWS) and RFC 7519 (JWT), this component ensures secure interoperability with external identity providers and authentication services.

## Core Cryptographic Primitives

The core cryptographic operations are abstracted through `jws.ts`, which leverages `crypto.subtle` to perform signing and verification. Rather than implementing proprietary crypto, Hono maps high-level algorithms (like `HS256`, `RS256`, or `ES256`) to the corresponding `SubtleCrypto` parameters. The `getKeyAlgorithm` function acts as a central registry for this mapping, converting a `SignatureAlgorithm` string into the required `KeyAlgorithm` structure.

```mermaid
flowchart TD
    A["User request"] --> B["jwt() middleware"]
    B --> C["Jwt.verify()"]
    C --> D["jws.ts: verifying()"]
    D --> E["jws.ts: importPublicKey()"]
    E --> F["crypto.subtle.verify()"]
```

Sources: [src/utils/jwt/jws.ts:29-48](https://github.com/blade47/hono/blob/main/src/utils/jwt/jws.ts#L29-L48), [src/utils/jwt/jws.ts:122-224](https://github.com/blade47/hono/blob/main/src/utils/jwt/jws.ts#L122-L224)

## JWT Lifecycle and Validation

The `Jwt.verify` function serves as the primary engine for token authentication. It performs a multi-stage validation process: token structure verification, header integrity, expiration/time-based checks, and final signature validation.

> [!IMPORTANT]
> The `verify` function strictly enforces that `alg` (algorithm) is provided. This prevents "None" algorithm attacks where an attacker replaces the algorithm header to bypass signature checks.

The flow ensures that security invariants are maintained before the signature is ever checked:

1. **Split**: Split the token by `.`. Expect exactly 3 parts.
2. **Decode**: Decode header and payload.
3. **Guard**: Validate existence and correctness of `alg` in header.
4. **Time Checks**: Evaluate `nbf` (Not Before), `exp` (Expiration), and `iat` (Issued At) against current server time.
5. **Verify**: Use `verifying()` to compare the signature of the `header.payload` string against the provided public key.

Sources: [src/utils/jwt/jwt.ts:96-188](https://github.com/blade47/hono/blob/main/src/utils/jwt/jwt.ts#L96-L188)

## JWK Verification and Security Invariants

The `verifyWithJwks` function provides a more advanced security model by fetching public keys from a URI or using a provided key set. It specifically hardens the system against Algorithm Confusion Attacks.

> [!WARNING]
> The system explicitly rejects symmetric algorithms (HS256, HS384, HS512) during JWK verification. This prevents an attacker from supplying an asymmetric public key as a symmetric "secret" to force the server into using a weak signature validation logic.

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| Symmetric algorithm rejection | Prevents key confusion attacks | Slightly higher complexity in key management |
| Explicit algorithm validation | Ensures strict cryptographic standards | Requires manual configuration of allowed algorithms |
| `kid` requirement | Enables key rotation | Requires metadata management in token headers |

Sources: [src/utils/jwt/jwt.ts:197-262](https://github.com/blade47/hono/blob/main/src/utils/jwt/jwt.ts#L197-L262)

## Authentication Middleware Surface

The `jwt` and `jwk` middleware wrap the core utilities to provide standard Hono middleware integration. They extract tokens from either the `Authorization` header (default: `Bearer`) or from cookie-based storage.

```ts
// Example: Basic JWT implementation
import { Hono } from 'hono'
import { jwt } from 'hono/jwt'

const app = new Hono()

app.use(
  '/auth/*',
  jwt({
    secret: 'super-secret-key',
    alg: 'HS256',
  })
)

app.get('/auth/page', (c) => {
  const payload = c.get('jwtPayload')
  return c.text(`Authorized, user: ${payload.sub}`)
})
```

The middleware provides an `unauthorizedResponse` helper that standardizes the `WWW-Authenticate` header, ensuring clients receive specific `error` and `error_description` fields when verification fails.

Sources: [src/middleware/jwt/jwt.ts:53-158](https://github.com/blade47/hono/blob/main/src/middleware/jwt/jwt.ts#L53-L158), [src/middleware/jwk/jwk.ts:48-168](https://github.com/blade47/hono/blob/main/src/middleware/jwk/jwk.ts#L48-L168)

## Cookie Signing and Integrity

Hono provides mechanisms for managing signed cookies to preserve authentication state securely. The `serializeSigned` and `parseSigned` utilities use HMAC-SHA256 signatures to ensure cookie values cannot be tampered with by the client.

```mermaid
sequenceDiagram
    participant App
    participant CookieUtils
    participant CryptoSubtle

    App->>CookieUtils: serializeSigned(key, val, secret)
    CookieUtils->>CryptoSubtle: crypto.subtle.sign(HMAC, val)
    CryptoSubtle-->>CookieUtils: signature
    CookieUtils-->>App: Set-Cookie: key=val.signature
```

The `verifySignature` utility uses `crypto.subtle.verify` to check the HMAC, ensuring the integrity of the cookie data before it is made available to the application.

Sources: [src/utils/cookie.ts:39-66](https://github.com/blade47/hono/blob/main/src/utils/cookie.ts#L39-L66), [src/utils/cookie.ts:140-165](https://github.com/blade47/hono/blob/main/src/utils/cookie.ts#L140-L165)

## CSRF Protection Mechanism

The `csrf` middleware complements JWT/Cookie-based auth by validating the origin of requests. It verifies that the request origin and/or `Sec-Fetch-Site` header correspond to a trusted value.

> [!TIP]
> Always use a combination of secure cookies (via `serializeSigned`) and `csrf()` middleware to create a layered defense-in-depth strategy for stateful web apps.

The logic follows a short-circuit evaluation:
1. Identify if the request method is "unsafe" (anything other than `GET` or `HEAD`).
2. Verify the `Content-Type` indicates it could have been triggered by a standard HTML form element.
3. Validate origin via an internal `isAllowedOrigin` handler or `Sec-Fetch-Site`. If both checks fail, the system returns a `403 Forbidden`.

Sources: [src/middleware/csrf/index.ts:94-151](https://github.com/blade47/hono/blob/main/src/middleware/csrf/index.ts#L94-L151)

## Related

- [[Authentication Middleware]]


---

## HTTP Helpers

URL: https://www.doc0.app/docs/552ca36e-f67e-41c3-a07a-def9bd9551b0/technical/http-helpers

<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/middleware/secure-headers/secure-headers.ts](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts)
- [src/adapter/aws-lambda/handler.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/handler.ts)
- [src/middleware/language/language.ts](https://github.com/blade47/hono/blob/main/src/middleware/language/language.ts)
- [src/context.ts](https://github.com/blade47/hono/blob/main/src/context.ts)
- [src/helper/proxy/index.ts](https://github.com/blade47/hono/blob/main/src/helper/proxy/index.ts)
- [src/utils/url.ts](https://github.com/blade47/hono/blob/main/src/utils/url.ts)
- [src/client/utils.ts](https://github.com/blade47/hono/blob/main/src/client/utils.ts)
- [src/utils/ipaddr.ts](https://github.com/blade47/hono/blob/main/src/utils/ipaddr.ts)
- [src/utils/accept.ts](https://github.com/blade47/hono/blob/main/src/utils/accept.ts)
- [src/client/fetch-result-please.ts](https://github.com/blade47/hono/blob/main/src/client/fetch-result-please.ts)
- [src/helper/conninfo/types.ts](https://github.com/blade47/hono/blob/main/src/helper/conninfo/types.ts)
- [src/helper/accepts/accepts.ts](https://github.com/blade47/hono/blob/main/src/helper/accepts/accepts.ts)
- [src/adapter/vercel/conninfo.ts](https://github.com/blade47/hono/blob/main/src/adapter/vercel/conninfo.ts)
- [src/helper/accepts/index.ts](https://github.com/blade47/hono/blob/main/src/helper/accepts/index.ts)
- [src/utils/mime.ts](https://github.com/blade47/hono/blob/main/src/utils/mime.ts)
- [src/helper/conninfo/index.ts](https://github.com/blade47/hono/blob/main/src/helper/conninfo/index.ts)
- [src/adapter/netlify/conninfo.ts](https://github.com/blade47/hono/blob/main/src/adapter/netlify/conninfo.ts)
- [src/helper/adapter/index.ts](https://github.com/blade47/hono/blob/main/src/helper/adapter/index.ts)
- [src/adapter/lambda-edge/conninfo.ts](https://github.com/blade47/hono/blob/main/src/adapter/lambda-edge/conninfo.ts)
- [src/adapter/bun/conninfo.ts](https://github.com/blade47/hono/blob/main/src/adapter/bun/conninfo.ts)
- [src/utils/headers.ts](https://github.com/blade47/hono/blob/main/src/utils/headers.ts)
- [src/adapter/deno/conninfo.ts](https://github.com/blade47/hono/blob/main/src/adapter/deno/conninfo.ts)
- [src/helper/websocket/index.ts](https://github.com/blade47/hono/blob/main/src/helper/websocket/index.ts)
- [src/adapter/cloudflare-workers/conninfo.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-workers/conninfo.ts)
- [src/adapter/netlify/mod.ts](https://github.com/blade47/hono/blob/main/src/adapter/netlify/mod.ts)
- [src/utils/http-status.ts](https://github.com/blade47/hono/blob/main/src/utils/http-status.ts)
- [src/adapter/cloudflare-pages/conninfo.ts](https://github.com/blade47/hono/blob/main/src/adapter/cloudflare-pages/conninfo.ts)
- [src/adapter/aws-lambda/conninfo.ts](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/conninfo.ts)
- [src/adapter/deno/websocket.ts](https://github.com/blade47/hono/blob/main/src/adapter/deno/websocket.ts)
</details>

"HTTP Helpers" in Hono serve as a modular suite of utility functions designed to abstract the complexities of standard web interfaces into developer-friendly APIs. By wrapping common HTTP tasks—such as header manipulation, connection metadata extraction, and content-negotiation—into coherent helpers, they allow developers to interact with the request/response lifecycle without manual implementation of low-level specs.

The design philosophy prioritizes platform portability and architectural separation. Because Hono is built on Web Standards, these helpers are designed to be environment-agnostic where possible, while exposing specific "adapter" modules for platform-specific capabilities (like AWS Lambda, Cloudflare, or Deno). This separation ensures the core framework remains lean while allowing the community to implement deep integrations for specialized environments.

These helpers exist to solve the "plumbing" problems of web development: safely extracting proxy-aware client IP addresses, parsing complex `Accept` headers into ranked arrays, and simplifying cross-platform WebSocket upgrades. They act as the bridge between the raw `Request`/`Response` interface and the semantic requirements of a feature-rich web application, maintaining stability across divergent runtime behaviors.

## Connection Information (`ConnInfo`)
The `ConnInfo` subsystem provides a unified API for retrieving network metadata, specifically the remote client address. Because different platforms (e.g., AWS Lambda, Bun, Cloudflare) propagate client IP addresses through different headers (like `cf-connecting-ip` or `x-forwarded-for`), Hono exposes platform-specific implementations that normalize this access through the `ConnInfo` interface.

> [!TIP]
> Use `getConnInfo(c)` to abstract away platform-specific header parsing; never manually parse `x-forwarded-for` if an adapter provides a `getConnInfo` implementation.

Sources: [src/helper/conninfo/types.ts:1-46](https://github.com/blade47/hono/blob/main/src/helper/conninfo/types.ts#L1-L46), [src/adapter/aws-lambda/conninfo.ts:1-74](https://github.com/blade47/hono/blob/main/src/adapter/aws-lambda/conninfo.ts#L1-L74)

## Content Negotiation (`Accepts`)
The `accepts` helper provides a mechanism to parse standard `Accept` headers (e.g., `Accept-Language`, `Accept`) and match them against a server's supported values. The mechanism uses a recursive parser that consumes the header string, tracking quality factors (`q`) and parameter keys/values, ultimately returning the best match based on client preference.

The selection logic follows a descending sort by quality factor. In the `defaultMatch` implementation, candidates are sorted such that `b.q - a.q` ensures the client's most-preferred media type or language is selected.

```mermaid
flowchart LR
    A["Raw Accept Header"] --> B["parseAccept()"]
    B --> C["Accept[] (parsed)"]
    C --> D["Sort by .q"]
    D --> E["Find first match in 'supports' array"]
    E --> F["Return winning type or 'default'"]
```

Sources: [src/utils/accept.ts:211-238](https://github.com/blade47/hono/blob/main/src/utils/accept.ts#L211-L238), [src/helper/accepts/accepts.ts:21-25](https://github.com/blade47/hono/blob/main/src/helper/accepts/accepts.ts#L21-L25)

## WebSocket Upgrades
The `upgradeWebSocket` helper abstracts the platform-specific ceremony required to transition an HTTP connection to a WebSocket connection. It defines a `WSContext` that mirrors standard event listeners (`onOpen`, `onMessage`, `onClose`, `onError`), providing a platform-independent way to define logic.

For platform implementations (e.g., `src/adapter/deno/websocket.ts`), this helper performs the necessary native upgrade, creates the context, and binds the provided listener functions.

```mermaid
sequenceDiagram
    participant App as Hono App
    participant Helper as upgradeWebSocket
    participant Platform as Deno/Worker
    App->>Helper: call upgradeWebSocket(events)
    Helper->>Platform: perform native upgrade
    Platform-->>Helper: return socket
    Helper->>Helper: instantiate WSContext
    Helper->>Platform: bind onOpen, onMessage, etc.
```

Sources: [src/helper/websocket/index.ts:70-91](https://github.com/blade47/hono/blob/main/src/helper/websocket/index.ts#L70-L91), [src/adapter/deno/websocket.ts:4-38](https://github.com/blade47/hono/blob/main/src/adapter/deno/websocket.ts#L4-L38)

## Secure Headers Middleware
The `secureHeaders` helper is a complex middleware responsible for injecting security-focused headers into the response. It pre-processes security options (CSP, `Permissions-Policy`, etc.) into a normalized set of header pairs.

The mechanism uses a callback-based architecture to defer the finalization of headers until the request lifecycle has progressed. A key invariant is the `Content-Security-Policy` callback which handles dynamic values like `nonce` generation.

> [!IMPORTANT]
> The `secureHeaders` middleware evaluates callbacks *before* calling `await next()`. This ensures that nonce values set in the context are available for the entire response lifecycle.

Sources: [src/middleware/secure-headers/secure-headers.ts:181-224](https://github.com/blade47/hono/blob/main/src/middleware/secure-headers/secure-headers.ts#L181-L224)

## Proxy Helper
The `proxy` helper facilitates request forwarding by stripping "Hop-by-Hop" headers per RFC 2616 (e.g., `Connection`, `Keep-Alive`). This is crucial for avoiding header injection attacks and maintaining protocol integrity when acting as a gateway.

The implementation performs a strict check: if `strictConnectionProcessing` is enabled, it parses the `Connection` header and removes any listed headers, throwing an `HTTPException` if it encounters invalid characters that violate the token syntax.

| Design Choice | Benefit | Cost |
| :--- | :--- | :--- |
| Hop-by-Hop stripping | Prevents header injection | Must maintain exclusion list |
| Middleware-style API | Familiar to Hono users | Requires async/await handling |
| RFC 9110 parsing | Correctness | Slightly higher CPU overhead |

Sources: [src/helper/proxy/index.ts:10-19](https://github.com/blade47/hono/blob/main/src/helper/proxy/index.ts#L10-L19), [src/helper/proxy/index.ts:60-78](https://github.com/blade47/hono/blob/main/src/helper/proxy/index.ts#L60-L78)

## URL Utilities
The `url.ts` utilities provide logic for routing and query parameter parsing. A notable mechanism is `_getQueryParam`, which is optimized for both simple and complex (encoded) URLs. It avoids the overhead of `URLSearchParams` for trivial cases by manually searching the `?` and `&` indices in the raw string.

```ts
// Example of manual index-based search used for optimization
while (keyIndex !== -1) {
  const trailingKeyCode = url.charCodeAt(keyIndex + key.length + 1)
  if (trailingKeyCode === 61) { // '='
    // Extract slice...
  }
}
```

Sources: [src/utils/url.ts:219-246](https://github.com/blade47/hono/blob/main/src/utils/url.ts#L219-L246)

## Related

- [[Request Lifecycle]]


---