Context object lifecycle
The Context object is instantiated for each request and kept until the response is returned. You can put values in it, set headers and a status code you want to return, and access HonoRequest and Response objects.
context
74 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
context.req property
The req property is an instance of HonoRequest that allows access to request details such as headers. You can call c.req.header('header-name') to retrieve a specific header value.
context.status() method
Set an HTTP status code with c.status(code). The default status code is 200. You do not have to use c.status() if the code is 200.
context.header() method
Set HTTP response headers using c.header('header-name', 'value'). This method sets a single header for the response.
context.body() method
Return an HTTP response body using c.body(content). You can also pass optional status code and headers as additional parameters: c.body(content, statusCode, headersObject). When returning text or HTML, it is recommended to use c.text() or c.html() instead.
context.text() method
Render text as Content-Type: text/plain using c.text('text-content'). This is the recommended method for returning plain text responses.
context.json() method
Render JSON as Content-Type: application/json using c.json(object). Pass a JavaScript object or array to be serialized to JSON.
context.html() method
Render HTML as Content-Type: text/html using c.html('<html-string>'). This is the recommended method for returning HTML responses.
context.notFound() method
Return a Not Found response using c.notFound(). The response can be customized with app.notFound().
context.redirect() method
Redirect to a URL using c.redirect(url) with a default status code of 302. You can optionally pass a status code as a second parameter: c.redirect(url, statusCode) to use status codes like 301 for permanent redirects.
context.res property
Access the Response object that will be returned using c.res. This allows you to modify response headers and other properties directly, such as c.res.headers.append('header-name', 'value').
context.set() and context.get() methods
Get and set arbitrary key-value pairs with a lifetime of the current request using c.set(key, value) and c.get(key). This allows passing specific values between middleware or from middleware to route handlers. The values are retained only within the same request and cannot be shared or persisted across different requests.
Type-safe Variables with Hono generic
Pass the Variables type as a generic to the Hono constructor to make c.set() and c.get() type-safe: new Hono<{ Variables: { key: type } }>(). Define a type alias and pass it to the constructor to ensure proper type inference.
context.var property
Access the value of a variable using c.var as an alternative to c.get(). Use c.var.variableName to access a variable that has been set in the context.
createMiddleware for custom context variables
Use createMiddleware from 'hono/factory' to create middleware that provides custom methods and values. Define the Env type with a Variables property containing the custom types, then use the middleware in route handlers or with app.use().
context.setRenderer() method
Set a layout for responses using c.setRenderer((content) => { ... }) within a custom middleware. The renderer function receives content and returns a Response. This allows you to wrap all rendered content in a consistent layout.
context.render() method
Create responses within a custom layout by calling c.render(content). First, use c.setRenderer() in middleware to define the layout, then c.render() will wrap the content in that layout and return the HTML response.
ContextRenderer interface for type-safe render
Define custom argument types for c.render() by augmenting the ContextRenderer interface in the hono module. For example: declare module 'hono' { interface ContextRenderer { (content: string | Promise<string>, head: { title: string }): Response | Promise<Response> } }
context.executionCtx property
Access Cloudflare Workers' ExecutionContext using c.executionCtx. This allows you to call c.executionCtx.waitUntil() to defer work until after the response is returned. The ExecutionContext also has an exports field that can be augmented via module declaration for type safety.
context.event property
Access Cloudflare Workers' FetchEvent using c.event. This is used with the Service Worker syntax for calling methods like c.event.waitUntil(). This approach is not recommended; use c.executionCtx instead.
context.env property for bindings
Access Cloudflare Workers bindings (environment variables, secrets, KV namespaces, D1 databases, R2 buckets, etc.) using c.env.BINDING_KEY. Define a Bindings type and pass it to the Hono constructor as new Hono<{ Bindings: Bindings }>() for type inference.
context.error property
If a handler throws an error, the error object is placed in c.error. You can access it in middleware after calling next() to check if an error occurred: if (c.error) { ... }
ContextVariableMap global interface augmentation
Augment the ContextVariableMap interface to define types for context variables globally across your entire application: declare module 'hono' { interface ContextVariableMap { variableName: type } }. This is appropriate only when a variable is set by middleware that is applied app-wide and is guaranteed to exist in the context.
ContextVariableMap pitfall: false type safety
ContextVariableMap adds types globally to all contexts regardless of whether the middleware that sets the variable has actually run. This means c.get('result') will appear type-safe even in handlers where the middleware was never registered, potentially hiding undefined bugs at runtime. Use the Variables generic on Hono instead for safer per-handler type definitions.
context.body() example with headers and status
Example: c.body('Thank you for coming', 201, { 'X-Message': 'Hello!', 'Content-Type': 'text/plain' }). This sets the response body, status code, and headers in a single call.
context.set() and c.var example with middleware
Example of setting a custom function in middleware and accessing it via c.var: type Env = { Variables: { echo: (str: string) => string } } const echoMiddleware = createMiddleware<Env>(async (c, next) => { c.set('echo', (str) => str) await next() }) app.get('/echo', echoMiddleware, (c) => { return c.text(c.var.echo('Hello!')) }) Or use app.use() to apply the middleware app-wide, passing Env to Hono's constructor.
context.setRenderer() and c.render() example
Example of defining a layout with setRenderer and using render: app.use(async (c, next) => { c.setRenderer((content) => { return c.html( <html><body><p>{content}</p></body></html> ) }) await next() }) app.get('/', (c) => { return c.render('Hello!') }) Output: <html><body><p>Hello!</p></body></html>
context.render() with custom arguments example
Example of custom render arguments: declare module 'hono' { interface ContextRenderer { (content: string | Promise<string>, head: { title: string }): Response | Promise<Response> } } app.use('/pages/*', async (c, next) => { c.setRenderer((content, head) => { return c.html( <html><head><title>{head.title}</title></head><body><header>{head.title}</header><p>{content}</p></body></html> ) }) await next() }) app.get('/pages/my-favorite', (c) => { return c.render(<p>Ramen and Sushi</p>, { title: 'My favorite' }) })
context.executionCtx.waitUntil() example
Example: app.get('/foo', async (c) => { c.executionCtx.waitUntil(c.env.KV.put(key, data)); ... }). This defers the KV put operation until after the response is returned in Cloudflare Workers.
context.env access example for Cloudflare Workers
Example: type Bindings = { MY_KV: KVNamespace } const app = new Hono<{ Bindings: Bindings }>() app.get('/', async (c) => { c.env.MY_KV.get('my-key') }) Bindings are defined in wrangler.toml and accessed via c.env.BINDING_KEY.
Get query parameter from request
Use `c.req.query('paramName')` to get a URL query parameter from the request.
Get path parameter from request
Use `c.req.param('paramName')` to get a path parameter from the request. Path parameters are defined in the route with a colon, e.g., `/posts/:id`.
Set response header
Use `c.header('headerName', 'headerValue')` to set a response header.
Adding response headers in middleware
Response headers can be set in middleware using c.res.headers.set(headerName, headerValue). The header value should be a string.
Access Cloudflare Bindings via c.env in Hono handler
Pass the CloudflareBindings interface to Hono as generics: const app = new Hono<{ Bindings: CloudflareBindings }>(). Then access bindings in a handler via c.env, for example: app.get('/', (c) => { return c.render(<h1>Hello! {c.env.MY_NAME}</h1>) })
param() method - get path parameters
Use c.req.param('id') to get a single path parameter by name. Use c.req.param() with no arguments to get all path parameters as an object. Example: app.get('/entry/:id', async (c) => { const id = c.req.param('id') }).
query() method - get querystring parameters
Use c.req.query('q') to get a single query parameter by name. Use c.req.query() with no arguments to get all query parameters as an object. Example: app.get('/search', async (c) => { const query = c.req.query('q') }).
queries() method - get multiple querystring values
Use c.req.queries('tags') to get multiple values of a querystring parameter, such as /search?tags=A&tags=B. Returns a string array.
header() method - get request header value
Use c.req.header('User-Agent') to get a specific header value. When called with no arguments, c.req.header() returns all headers as a record with lowercase keys. To retrieve headers with uppercase names, you must pass the header name as an argument, for example c.req.header('X-Foo').
parseBody() method - parse form data
Use await c.req.parseBody() to parse request body of type multipart/form-data or application/x-www-form-urlencoded. Returns an object where each value is either a string or File.
parseBody() with single file
When accessing body['foo'] from parseBody(), the value is (string | File). If multiple files are uploaded to the same field name, the last one will be used.
parseBody() with multiple files - array suffix
To get multiple files from the same field, use body['foo[]']. The [] postfix is required, and body['foo[]'] is always (string | File)[].
parseBody() 'all' option - handle multiple values with same name
Use parseBody({ all: true }) to handle multiple input fields or files with the same name, such as <input type="file" multiple /> or multiple checkboxes. The 'all' option is disabled by default. With 'all' enabled, if body['foo'] contains multiple items, it becomes (string | File)[]; if single, it remains (string | File).
parseBody() 'dot' option - parse dot notation in form data
Use parseBody({ dot: true }) to structure the return value based on dot notation. For example, form fields named 'obj.key1' and 'obj.key2' will be parsed into { obj: { key1: 'value1', key2: 'value2' } }.
json() method - parse JSON request body
Use await c.req.json() to parse a request body of type application/json.
text() method - parse text request body
Use await c.req.text() to parse a request body of type text/plain.
arrayBuffer() method - parse as ArrayBuffer
Use await c.req.arrayBuffer() to parse the request body as an ArrayBuffer.
blob() method - parse as Blob
Use await c.req.blob() to parse the request body as a Blob.
formData() method - parse as FormData
Use await c.req.formData() to parse the request body as FormData.
valid() method - get validated data
Use c.req.valid('form') to get validated data from a specific target. Available targets are: form, json, query, header, cookie, param. See the Validation section for usage examples.
path property - get request pathname
Access c.req.path to get the request pathname. For example, accessing /about/me will return '/about/me'.
url property - get full request URL
Access c.req.url to get the full request URL string. For example, a request to /about/me returns 'http://localhost:8787/about/me'.
method property - get HTTP method
Access c.req.method to get the HTTP method name of the request, such as 'GET', 'POST', etc.
raw property - get raw Request object
Access c.req.raw to get the underlying Request object. This allows access to runtime-specific properties, such as c.req.raw.cf?.hostMetadata? for Cloudflare Workers.
cloneRawRequest() function - clone request after body consumption
Use cloneRawRequest(c.req) to clone the raw Request object even after the request body has been consumed by validators or HonoRequest methods. This allows you to parse the body again without errors. Import from 'hono/request'.
routePath property - deprecated in v4.8.0
The routePath property is deprecated as of v4.8.0. Use the routePath() function from the Route Helper instead. It returns the registered path pattern, such as '/posts/:id' when accessed via /posts/123.
matchedRoutes property - deprecated in v4.8.0
The matchedRoutes property is deprecated as of v4.8.0. Use the matchedRoutes() function from the Route Helper instead. It returns an array of matched routes within the handler, each with handler, method, and path properties, useful for debugging.
Type Bindings in Hono for Cloudflare Pages
Define a Bindings type interface with your Variables and KV namespaces, then pass it to Hono: type Bindings = { MY_NAME: string; MY_KV: KVNamespace }; const app = new Hono<{ Bindings: Bindings }>()
Access Bindings in Cloudflare Pages handlers
Access Bindings in route handlers via c.env. For example, use c.env.MY_KV for KV operations and c.env.MY_NAME for Variables: await c.env.MY_KV.put('name', c.env.MY_NAME); const name = await c.env.MY_KV.get('name');
Access EventContext in Cloudflare Pages middleware
Access Cloudflare Pages EventContext via c.env.eventContext in handleMiddleware. Set data on it like c.env.eventContext.data.user = 'Joe', which can then be accessed in handlers via c.env.eventContext.