hono-guide

Hono Guide

Hono is a small, simple, and ultrafast web framework built on Web Standards. It works on any JavaScript runtime: Cloudflare Workers, Bun, Deno, Node.js, AWS Lambda, Vercel, Netlify, Fastly Compute, and more. The same code runs on all platforms.

Quick Start

npm create hono@latest my-app

import { Hono } from 'hono'
const app = new Hono()

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

export default app

Core Concepts

Routing

// HTTP methods
app.get('/posts', (c) => c.json({ posts }))
app.post('/posts', (c) => c.json({ message: 'Created' }, 201))
app.put('/posts/:id', (c) => c.json({ message: 'Updated' }))
app.delete('/posts/:id', (c) => c.json({ message: 'Deleted' }))

// Path parameters
app.get('/users/:id', (c) => {
  const id = c.req.param('id')  // inferred type
  return c.json({ id })
})

// Optional params
app.get('/api/animal/:type?', (c) => c.text('Animal!'))

// Wildcard
app.get('/wild/*/card', (c) => c.text('Matched!'))

// Regexp
app.get('/post/:date{[0-9]+}/:title{[a-z]+}', (c) => {
  const { date, title } = c.req.param()
  return c.json({ date, title })
})

// Chained routes
app.get('/endpoint', (c) => c.text('GET'))
   .post((c) => c.text('POST'))
   .delete((c) => c.text('DELETE'))

Context API (c)

The Context object provides all request/response methods:

// Response methods
c.text('Hello')                          // text/plain
c.json({ message: 'Hello' })            // application/json
c.html('<h1>Hello</h1>')                // text/html
c.redirect('/new-path')                  // 302 redirect
c.redirect('/new-path', 301)            // 301 redirect
c.notFound()                             // 404
c.body(data, 200, headers)             // raw response

// Status & headers
c.status(201)
c.header('X-Custom', 'value')

// Request data
c.req.param('id')                       // path param
c.req.query('q')                        // query string
c.req.queries('tags')                   // multiple values
c.req.header('Authorization')           // header
const body = await c.req.json()         // JSON body
const form = await c.req.parseBody()    // form data

// Variables (pass data between middleware and handlers)
c.set('user', userObj)
const user = c.get('user')
// or: c.var.user

// Environment (Cloudflare bindings, env vars)
c.env.MY_KV         // KV namespace
c.env.DATABASE_URL   // env variable

Middleware

Middleware runs before/after handlers in onion-layer order:

import { logger } from 'hono/logger'
import { cors } from 'hono/cors'
import { basicAuth } from 'hono/basic-auth'

// Apply to all routes
app.use(logger())
app.use(cors())

// Apply to specific paths
app.use('/api/*', cors({ origin: 'https://example.com' }))
app.use('/admin/*', basicAuth({ username: 'admin', password: 'secret' }))

// Custom middleware
app.use(async (c, next) => {
  const start = Date.now()
  await next()
  c.header('X-Response-Time', `${Date.now() - start}ms`)
})

Execution order: middleware 1 start -> middleware 2 start -> handler -> middleware 2 end -> middleware 1 end

Built-in Middleware (import from hono/<name>)

Middleware	Import	Purpose
basicAuth	hono/basic-auth	HTTP Basic authentication
bearerAuth	hono/bearer-auth	Bearer token authentication
jwt	hono/jwt	JWT authentication
cors	hono/cors	CORS headers
csrf	hono/csrf	CSRF protection
logger	hono/logger	Request logging
secureHeaders	hono/secure-headers	Security headers (Helmet-like)
etag	hono/etag	ETag caching
cache	hono/cache	Cache API (CF Workers, Deno)
compress	hono/compress	Response compression
bodyLimit	hono/body-limit	Request body size limit
timeout	hono/timeout	Request timeout
prettyJSON	hono/pretty-json	Pretty-print JSON with ?pretty
requestId	hono/request-id	Unique request ID per request
ipRestriction	hono/ip-restriction	IP allow/deny lists
languageDetector	hono/language	i18n language detection
jsxRenderer	hono/jsx-renderer	JSX layout renderer
contextStorage	hono/context-storage	AsyncLocalStorage for Context
methodOverride	hono/method-override	HTTP method override
timing	hono/timing	Server-Timing header

Helpers (import from hono/<name>)

Helper	Import	Purpose
Cookie	hono/cookie	get/set/delete cookies
JWT	hono/jwt	sign/verify/decode JWT
Streaming	hono/streaming	stream, streamText, streamSSE
WebSocket	Platform-specific	upgradeWebSocket handler
HTML	hono/html	html template literals
CSS	hono/css	CSS-in-JS(X)
Factory	hono/factory	createMiddleware, createHandlers
Testing	hono/testing	testClient for typed testing
Proxy	hono/proxy	Reverse proxy helper
SSG	hono/ssg	Static site generation
Accepts	hono/accepts	Content negotiation (Accept-*)
Adapter	hono/adapter	env(), getRuntimeKey()
ConnInfo	Platform-specific	Client remote address, connection info
Dev	hono/dev	showRoutes(), getRouterName()
Route	hono/route	matchedRoutes(), routePath()

Larger Applications

Use app.route() to split into sub-apps:

// authors.ts
const authors = new Hono()
  .get('/', (c) => c.json('list authors'))
  .post('/', (c) => c.json('create author', 201))
  .get('/:id', (c) => c.json(`get ${c.req.param('id')}`))
export default authors

// index.ts
import authors from './authors'
import books from './books'

const app = new Hono()
app.route('/authors', authors)
app.route('/books', books)
export default app

Type-Safe RPC

Share API types between server and client:

// server.ts
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'

const route = app.post('/posts',
  zValidator('form', z.object({ title: z.string(), body: z.string() })),
  (c) => c.json({ ok: true, message: 'Created!' }, 201)
)
export type AppType = typeof route

// client.ts
import { hc } from 'hono/client'
import type { AppType } from './server'

const client = hc<AppType>('http://localhost:8787/')
const res = await client.posts.$post({
  form: { title: 'Hello', body: 'World' }
})

Key RPC rule: chain route definitions for type inference to work.

Validation

import { validator } from 'hono/validator'

app.post('/posts',
  validator('json', (value, c) => {
    if (!value.title) return c.text('Invalid!', 400)
    return { title: value.title }
  }),
  (c) => {
    const { title } = c.req.valid('json')
    return c.json({ title }, 201)
  }
)

Validation targets: json, form, query, header, param, cookie.

Presets

Preset	Import	Use Case
hono (default)	import { Hono } from 'hono'	Most cases, long-lived servers
hono/quick	import { Hono } from 'hono/quick'	Per-request initialization
hono/tiny	import { Hono } from 'hono/tiny'	Under 14KB, resource-limited

Platform Handler Patterns

// Cloudflare Workers / Bun - export default
export default app

// Node.js
import { serve } from '@hono/node-server'
serve(app)

// AWS Lambda
import { handle } from 'hono/aws-lambda'
export const handler = handle(app)

// Deno
Deno.serve(app.fetch)

// Vercel / Next.js
import { handle } from 'hono/vercel'
export const GET = handle(app)
export const POST = handle(app)

// Netlify
import { handle } from 'hono/netlify'
export default handle(app)

Testing

// Use app.request() for testing
const res = await app.request('/posts')
expect(res.status).toBe(200)
expect(await res.json()).toEqual({ posts: [] })

// POST with JSON
const res = await app.request('/posts', {
  method: 'POST',
  body: JSON.stringify({ title: 'Hello' }),
  headers: { 'Content-Type': 'application/json' },
})

// Mock env (3rd argument)
const res = await app.request('/posts', {}, { API_KEY: 'test' })

Key Rules

1. Don't create RoR-like controllers - define handlers inline for type inference
2. Chain routes for RPC type inference to work: const app = new Hono().get(...).post(...)
3. Middleware order matters - registered first runs first (before next), last (after next)
4. Export typeof route not typeof app for RPC
5. For RPC with app.route(): chain the .route() calls and export the chained result: const routes = app.route('/a', a).route('/b', b); export type AppType = typeof routes
6. Use lowercase header names when validating headers
7. Set Content-Type header when testing json or form validators
8. next() never throws - Hono catches errors and passes to app.onError()
9. Route registration order matters - register sub-routes before mounting with app.route()

Common Errors

1. Empty body in validator: Missing Content-Type header in request
2. RPC types not working: Routes not chained, or Hono version mismatch between client/server
3. 404 on sub-routes: Routes registered after app.route() call (wrong order)
4. Streaming not working on CF Workers: Add c.header('Content-Encoding', 'Identity')
5. WebSocket + CORS conflict: upgradeWebSocket() modifies headers internally, conflicts with header-modifying middleware
6. Slow IDE with RPC: Too many routes cause excessive type instantiation. Fix: ensure matching Hono versions, split clients per sub-app, or pre-compile types with hcWithType pattern (see references/rpc-validation.md Section 21)

Reference Files

• references/api-reference.md - Context, HonoRequest, App, HTTPException, Routing
• references/middleware-auth.md - Middleware concepts, Auth (Basic, Bearer, JWT, JWK)
• references/middleware-security.md - Security (CORS, CSRF, Secure Headers, IP Restriction), Access Control (Combine), Custom Middleware, Best Practices
• references/middleware-request-response.md - Request Processing (BodyLimit, Compress, MethodOverride, TrailingSlash), Response Processing (Cache, ETag, PrettyJSON)
• references/middleware-utilities.md - Utilities (ContextStorage, Logger, RequestID, Timing, Timeout), Rendering (JSXRenderer), i18n (Language)
• references/helpers-auth-streaming.md - Cookie, JWT (sign/verify/decode, all algorithms), Streaming (stream, streamText, streamSSE), WebSocket
• references/helpers-rendering.md - HTML (tagged templates, raw, XSS protection), CSS (scoped styles, keyframes, cx, global styles, CSP nonce)
• references/helpers-factory-testing.md - Factory, Testing (testClient), Proxy, SSG
• references/helpers-runtime.md - Accepts (content negotiation), Adapter (env, getRuntimeKey), ConnInfo, Dev (showRoutes), Route
• references/platforms-core.md - Cloudflare Workers, Cloudflare Pages, Bun, Deno, Node.js
• references/platforms-serverless.md - AWS Lambda, Lambda@Edge, Vercel, Next.js, Netlify
• references/platforms-other.md - Azure, GCR, Fastly, Supabase, Alibaba, Service Worker, WebAssembly, Platform Comparison
• references/rpc-validation.md - RPC client, validators, Zod, Standard Schema
• references/jsx.md - JSX, Client Components, JSX Renderer, Suspense, streaming
• references/patterns.md - Best practices, testing, error handling, validation patterns, RPC troubleshooting (hcWithType), View Transitions, Service Worker