Hono
Overview
Hono is a small, ultrafast web framework built on Web Standards that runs on any JavaScript runtime including Cloudflare Workers, Bun, Deno, Node.js, Vercel, and AWS Lambda. Application code is portable across runtimes; only the entry point and adapter differ per platform.
When to use: Edge-first APIs, Cloudflare Workers services, multi-runtime applications, lightweight REST/RPC servers, middleware-heavy request pipelines, type-safe client-server communication.
When NOT to use: Full-stack SSR frameworks (use Next.js/Remix), heavy ORM-driven monoliths where Express ecosystem maturity matters, applications that need deep Node.js-only APIs without Web Standard equivalents.
Quick Reference
| Pattern |
API |
Key Points |
| Basic routing |
app.get('/path', handler) |
Supports get, post, put, delete, patch, all |
| Path parameters |
app.get('/user/:id', handler) |
Access via c.req.param('id') |
| Regex constraints |
app.get('/post/:id{[0-9]+}', handler) |
Inline regex in path parameter |
| Wildcard |
app.get('/files/*', handler) |
Matches any sub-path |
| Route grouping |
app.route('/api', subApp) |
Mount sub-applications |
| Middleware |
app.use(middleware()) |
Executes in registration order |
| Path middleware |
app.use('/auth/*', jwt(...)) |
Scope middleware to paths |
| JSON response |
c.json({ key: 'value' }) |
Sets Content-Type automatically |
| Text response |
c.text('hello') |
Returns plain text |
| HTML response |
c.html('<h1>Hi</h1>') |
Returns HTML content |
| Status + header |
c.status(201), c.header('X-Key', 'val') |
Chain before response |
| Redirect |
c.redirect('/new-path', 301) |
Default status is 302 |
| Request body |
c.req.json(), c.req.parseBody() |
JSON or form data parsing |
| Query params |
c.req.query('page') |
Single query parameter |
| Context variables |
c.set('user', data) / c.get('user') |
Type-safe middleware data passing |
| Zod validation |
zValidator('json', schema) |
@hono/zod-validator package |
| RPC client |
hc<AppType>(url) |
End-to-end type-safe API calls |
| Error handler |
app.onError((err, c) => ...) |
Global error handling |
| Not found |
app.notFound((c) => ...) |
Custom 404 handler |
| Environment |
c.env.BINDING_KEY |
Access runtime bindings/env vars |
| Adapter helper |
env(c) from hono/adapter |
Unified env access across runtimes |
| WebSocket |
upgradeWebSocket() from runtime adapter |
WebSocket helper with RPC support |
| Test client |
testClient(app) from hono/testing |
Type-safe testing without HTTP server |
| JSX streaming |
jsxRenderer({ stream: true }) |
SSR streaming with Suspense support |
Common Mistakes
| Mistake |
Correct Pattern |
| Registering middleware after handlers |
Register middleware before the handlers it should apply to |
Using app.route() without chaining for RPC types |
Chain route methods (app.route('/a', a).route('/b', b)) and export typeof routes |
Forgetting export default app for edge runtimes |
Cloudflare Workers, Bun, and Deno require the default export |
Using compress() on Cloudflare Workers or Deno Deploy |
These platforms compress automatically; skip the middleware |
| Mixing Hono and middleware versions in Deno |
Pin all hono imports to the same version to avoid type mismatches |
Wrapping next() in try/catch inside middleware |
Hono catches thrown errors and routes to app.onError(); next() never throws |
Defining routes with app.get() but exporting typeof app for RPC |
Export the type of the chained route variable, not the app instance |
Using new Hono() without generics for typed context |
Pass Hono<{ Variables: MyVars }> to enable typed c.get()/c.set() |
Returning c.json() without status for created resources |
Pass status as second argument: c.json(data, 201) |
Not using createMiddleware() for reusable middleware |
Import from hono/factory to preserve type inference when extracting middleware |
Delegation
If the zod or typescript-patterns skill is available, delegate schema and type-level tasks to it.
Otherwise, recommend: npx skills add oakoss/agent-skills --skill typescript-patterns
If a Cloudflare Workers skill is available, delegate platform-specific configuration to it.
References
- Route definitions, path params, groups, and method handlers
- Built-in and custom middleware patterns
- Context object, request parsing, and response helpers
- Zod validator middleware and request validation
- RPC client and end-to-end type safety
- Runtime adapters for Cloudflare, Bun, Node.js, Deno, and more
- Testing with testClient, WebSocket helper, and JSX streaming
1---2name: hono3description: Hono ultrafast web framework for edge and server runtimes. Use when building APIs, middleware chains, or edge functions on Cloudflare Workers, Bun, Node.js, or Deno. Use for hono, api, routing, middleware, cloudflare-workers, edge, rpc, validator, context.4license: MIT5---6
7# Hono
8
9## Overview
10
11Hono is a small, ultrafast web framework built on Web Standards that runs on any JavaScript runtime including Cloudflare Workers, Bun, Deno, Node.js, Vercel, and AWS Lambda. Application code is portable across runtimes; only the entry point and adapter differ per platform.
12
13**When to use:** Edge-first APIs, Cloudflare Workers services, multi-runtime applications, lightweight REST/RPC servers, middleware-heavy request pipelines, type-safe client-server communication.
14
15**When NOT to use:** Full-stack SSR frameworks (use Next.js/Remix), heavy ORM-driven monoliths where Express ecosystem maturity matters, applications that need deep Node.js-only APIs without Web Standard equivalents.
16
17## Quick Reference
18
19| Pattern | API | Key Points |
20| ----------------- | ------------------------------------------- | ------------------------------------------- |
21| Basic routing | `app.get('/path', handler)` | Supports get, post, put, delete, patch, all |
22| Path parameters | `app.get('/user/:id', handler)` | Access via `c.req.param('id')` |
23| Regex constraints | `app.get('/post/:id{[0-9]+}', handler)` | Inline regex in path parameter |
24| Wildcard | `app.get('/files/*', handler)` | Matches any sub-path |
25| Route grouping | `app.route('/api', subApp)` | Mount sub-applications |
26| Middleware | `app.use(middleware())` | Executes in registration order |
27| Path middleware | `app.use('/auth/*', jwt(...))` | Scope middleware to paths |
28| JSON response | `c.json({ key: 'value' })` | Sets Content-Type automatically |
29| Text response | `c.text('hello')` | Returns plain text |
30| HTML response | `c.html('<h1>Hi</h1>')` | Returns HTML content |
31| Status + header | `c.status(201)`, `c.header('X-Key', 'val')` | Chain before response |
32| Redirect | `c.redirect('/new-path', 301)` | Default status is 302 |
33| Request body | `c.req.json()`, `c.req.parseBody()` | JSON or form data parsing |
34| Query params | `c.req.query('page')` | Single query parameter |
35| Context variables | `c.set('user', data)` / `c.get('user')` | Type-safe middleware data passing |
36| Zod validation | `zValidator('json', schema)` | `@hono/zod-validator` package |
37| RPC client | `hc<AppType>(url)` | End-to-end type-safe API calls |
38| Error handler | `app.onError((err, c) => ...)` | Global error handling |
39| Not found | `app.notFound((c) => ...)` | Custom 404 handler |
40| Environment | `c.env.BINDING_KEY` | Access runtime bindings/env vars |
41| Adapter helper | `env(c)` from `hono/adapter` | Unified env access across runtimes |
42| WebSocket | `upgradeWebSocket()` from runtime adapter | WebSocket helper with RPC support |
43| Test client | `testClient(app)` from `hono/testing` | Type-safe testing without HTTP server |
44| JSX streaming | `jsxRenderer({ stream: true })` | SSR streaming with Suspense support |
45
46## Common Mistakes
47
48| Mistake | Correct Pattern |
49| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
50| Registering middleware after handlers | Register middleware before the handlers it should apply to |
51| Using `app.route()` without chaining for RPC types | Chain route methods (`app.route('/a', a).route('/b', b)`) and export `typeof routes` |
52| Forgetting `export default app` for edge runtimes | Cloudflare Workers, Bun, and Deno require the default export |
53| Using `compress()` on Cloudflare Workers or Deno Deploy | These platforms compress automatically; skip the middleware |
54| Mixing Hono and middleware versions in Deno | Pin all `hono` imports to the same version to avoid type mismatches |
55| Wrapping `next()` in try/catch inside middleware | Hono catches thrown errors and routes to `app.onError()`; `next()` never throws |
56| Defining routes with `app.get()` but exporting `typeof app` for RPC | Export the type of the chained route variable, not the app instance |
57| Using `new Hono()` without generics for typed context | Pass `Hono<{ Variables: MyVars }>` to enable typed `c.get()`/`c.set()` |
58| Returning `c.json()` without status for created resources | Pass status as second argument: `c.json(data, 201)` |
59| Not using `createMiddleware()` for reusable middleware | Import from `hono/factory` to preserve type inference when extracting middleware |
60
61## Delegation
62
63> If the `zod` or `typescript-patterns` skill is available, delegate schema and type-level tasks to it.
64> Otherwise, recommend: `npx skills add oakoss/agent-skills --skill typescript-patterns`
65>
66> If a Cloudflare Workers skill is available, delegate platform-specific configuration to it.
67
68## References
69
70- [Route definitions, path params, groups, and method handlers](references/routing.md)
71- [Built-in and custom middleware patterns](references/middleware.md)
72- [Context object, request parsing, and response helpers](references/context-and-helpers.md)
73- [Zod validator middleware and request validation](references/validation.md)
74- [RPC client and end-to-end type safety](references/rpc-client.md)
75- [Runtime adapters for Cloudflare, Bun, Node.js, Deno, and more](references/adapters.md)
76- [Testing with testClient, WebSocket helper, and JSX streaming](references/testing-and-websocket.md)
oakoss