Hono API
Setup
# Bun
bun create hono@latest my-app
# or add to existing
bun add hono
# Node.js
bun add hono @hono/node-server
Basic App
import { Hono } from 'hono'
import { logger } from 'hono/logger'
import { cors } from 'hono/cors'
import { prettyJSON } from 'hono/pretty-json'
const app = new Hono()
// Middleware
app.use('*', logger())
app.use('*', cors())
app.use('*', prettyJSON())
// Routes
app.get('/', (c) => c.text('Hello Hono!'))
app.get('/health', (c) => c.json({ status: 'ok' }))
// Bun
export default app
// Node.js
import { serve } from '@hono/node-server'
serve({ fetch: app.fetch, port: 3000 })
Routing
const app = new Hono()
// Methods
app.get('/users', handler)
app.post('/users', handler)
app.put('/users/:id', handler)
app.patch('/users/:id', handler)
app.delete('/users/:id', handler)
// Params, query, body
app.get('/users/:id', (c) => {
const id = c.req.param('id')
const page = c.req.query('page') ?? '1'
return c.json({ id, page })
})
app.post('/users', async (c) => {
const body = await c.req.json()
return c.json({ created: body }, 201)
})
// Route groups
const api = new Hono().basePath('/api')
const users = new Hono()
users.get('/', listUsers)
users.post('/', createUser)
users.get('/:id', getUser)
api.route('/users', users)
app.route('/', api)
Validation with Zod Validator
bun add @hono/zod-validator zod
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'
const createUserSchema = z.object({
name: z.string().min(1),
email: z.string().email(),
age: z.number().int().min(0).optional(),
})
app.post('/users',
zValidator('json', createUserSchema),
async (c) => {
const data = c.req.valid('json') // fully typed
// create user...
return c.json({ id: 1, ...data }, 201)
}
)
// Query validation
const querySchema = z.object({
page: z.coerce.number().default(1),
limit: z.coerce.number().max(100).default(20),
})
app.get('/users', zValidator('query', querySchema), (c) => {
const { page, limit } = c.req.valid('query')
return c.json({ page, limit })
})
Middleware
// Auth middleware
import { createMiddleware } from 'hono/factory'
import { HTTPException } from 'hono/http-exception'
const authMiddleware = createMiddleware(async (c, next) => {
const token = c.req.header('Authorization')?.replace('Bearer ', '')
if (!token) throw new HTTPException(401, { message: 'Unauthorized' })
const user = await verifyToken(token)
c.set('user', user) // set context variable
await next()
})
app.use('/api/*', authMiddleware)
app.get('/api/me', (c) => {
const user = c.get('user')
return c.json(user)
})
RPC Client (type-safe)
// server: export route type
const route = app.get('/users/:id', zValidator('param', z.object({ id: z.string() })), (c) => {
return c.json({ id: c.req.valid('param').id, name: 'Alice' })
})
export type AppType = typeof route
// client: fully typed
import { hc } from 'hono/client'
import type { AppType } from './server'
const client = hc<AppType>('http://localhost:3000')
const res = await client.users[':id'].$get({ param: { id: '1' } })
const data = await res.json() // typed: { id: string, name: string }
Error Handling
import { HTTPException } from 'hono/http-exception'
// Throw typed HTTP errors anywhere
app.get('/users/:id', async (c) => {
const user = await db.findUser(c.req.param('id'))
if (!user) throw new HTTPException(404, { message: 'User not found' })
return c.json(user)
})
// Global error handler
app.onError((err, c) => {
if (err instanceof HTTPException) {
return c.json({ error: err.message }, err.status)
}
console.error(err)
return c.json({ error: 'Internal Server Error' }, 500)
})
// 404 handler
app.notFound((c) => c.json({ error: 'Not found' }, 404))
Cloudflare Workers
// Compatible out of the box — just export default app
// wrangler.toml
// name = "my-api"
// compatibility_date = "2025-01-01"
export default app
// Access CF bindings
app.get('/kv', async (c) => {
const value = await c.env.MY_KV.get('key')
return c.json({ value })
})
Context Variables (Type-safe)
type Variables = {
user: { id: string; email: string }
}
const app = new Hono<{ Variables: Variables }>()
Heldinhow