Claude Code for Hono Framework (2026)

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.

Configure permissions → Build your settings with our Permission Configurator.

Frequently Asked Questions

What is the minimum setup required?

You need Claude Code installed (Node.js 18+), a project with a CLAUDE.md file, and the relevant toolchain for your project type (e.g., npm for JavaScript, pip for Python). The CLAUDE.md file should describe your project structure, conventions, and common commands so Claude Code can work effectively.

How long does the initial setup take?

For a typical project, initial setup takes 10-20 minutes. This includes creating the CLAUDE.md file, configuring .claude/settings.json for permissions, and running a test task to verify everything works. Subsequent sessions start immediately because the configuration persists.

Can I use this with a team?

Yes. Commit your .claude/ directory and CLAUDE.md to version control so the entire team uses the same configuration. Each developer can add personal preferences in ~/.claude/settings.json (user-level) without affecting the project configuration. Review CLAUDE.md changes in pull requests like any other configuration file.

What if Claude Code produces incorrect output?

First check that your CLAUDE.md accurately describes your project conventions. Incorrect or outdated context is the most common cause of wrong output. If the output is still wrong, provide feedback in the same session — Claude Code learns from corrections within a conversation. For persistent issues, add explicit rules to CLAUDE.md (e.g., “Always use single quotes” or “Never modify files in the config/ directory”).