Claude Code for Hono Framework — Workflow Guide

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Setup

You are building a web API with Hono, the ultrafast web framework that runs on Cloudflare Workers, Deno, Bun, and Node.js with the same code. Hono uses the Web Standard API (Request/Response) and has Express-like routing with much less overhead. Claude Code can write Hono APIs, but it generates Express code with Node.js-specific modules.

What Claude Code Gets Wrong By Default

  1. Writes Express middleware and routes. Claude generates app.get('/users', (req, res) => { res.json(...) }). Hono uses app.get('/users', (c) => c.json(...)) with a context object, not separate req/res.

  2. Imports Node.js built-in modules. Claude uses const fs = require('fs') or import { createServer } from 'http'. Hono is designed for edge runtimes where Node built-ins are unavailable. Use Web APIs instead.

  3. Uses body-parser middleware. Claude adds app.use(express.json()) for body parsing. Hono parses request bodies with c.req.json() — built-in, no middleware needed.

  4. Creates separate server startup files. Claude writes app.listen(3000) startup code. On Cloudflare Workers, Deno Deploy, or Vercel Edge, the framework handles server lifecycle. Only Node.js adapter needs explicit serve().

The CLAUDE.md Configuration

# Hono API Project

## Framework
- API: Hono (edge-first, Web Standard API)
- Runtime: Cloudflare Workers (primary), Node.js (fallback)
- Validation: @hono/zod-validator middleware
- OpenAPI: @hono/zod-openapi for typed routes

## Hono Rules
- Route handler: app.get('/path', (c) => c.json({ data }))
- Context object (c): c.req for request, c.json/c.text for response
- Body parsing: const body = await c.req.json()
- Path params: c.req.param('id')
- Query params: c.req.query('page')
- Middleware: app.use('/*', cors(), logger())
- Error handling: app.onError((err, c) => c.json({ error }, 500))
- No Node.js built-ins — use Web APIs (fetch, Request, Response)

## Conventions
- Routes in src/routes/ directory, imported into src/index.ts
- Group routes: const users = new Hono(); app.route('/users', users)
- Validation: zValidator('json', schema) middleware on routes
- Types exported for client-side use (RPC-style with hono/client)
- Middleware in src/middleware/ directory
- Environment bindings typed: Bindings type for Cloudflare

Workflow Example

You want to create a type-safe API with validation and OpenAPI docs. Prompt Claude Code:

“Create a Hono API with a /users endpoint that supports GET (list with pagination) and POST (create with validation). Use Zod for request validation and generate OpenAPI documentation for the endpoints.”

Claude Code should create routes using @hono/zod-openapi with Zod schemas for request validation and response types, route definitions with createRoute() that include OpenAPI metadata, and the Swagger UI middleware for documentation at /docs.

Common Pitfalls

  1. Middleware order matters. Claude adds CORS middleware after route definitions. Like Express, Hono middleware runs top-to-bottom — CORS and auth middleware must be registered before the routes they protect.

  2. Cloudflare bindings not typed. Claude accesses c.env.DATABASE without defining the Bindings type. Create a type Bindings = { DATABASE: D1Database } and pass it as a generic: new Hono<{ Bindings: Bindings }>() for type-safe environment access.

  3. Using c.body() for JSON responses. Claude writes c.body(JSON.stringify(data)) instead of c.json(data). The c.json() helper sets the Content-Type header automatically and handles serialization — c.body() returns raw text.