Orientation Arc
Routing Algorithms
Rendering and JSX
Runtime Adapters
Middleware Ecosystem
Developer Helpers
System Utilities
The following files were used as context for generating this wiki page:
"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).
Context Interface and ResponsibilitiesThe 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.
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).
The flow of a request starts at the application's fetch method and proceeds through the following orchestration chain:
HonoBase class's fetch method initiates the request handling process.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.compose() (from hono-base.ts), which wraps the handlers into a middleware pipeline. Each handler receives the Context instance.Context (using .set(), .get(), or response helpers like .json()).Response object, which is then returned through the pipeline and dispatched to the platform-specific adapter.Sources: src/hono-base.ts:406-466, src/context.ts:352-361
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.
APIGatewayProxyEvent, ALBProxyEvent, LatticeProxyEventV2). These extract path, method, headers, and body from the event and map them to standard Web Request types (lines 318-341).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.The context exposes several helper methods for common HTTP operations. These methods are designed to facilitate communication.
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).
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.
Sources: src/hono-base.ts:35-42, src/hono-base.ts:462-464
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.
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, src/context.ts:541, src/context.ts:704