# Hono

> Hono best-practice guidance for building, refactoring, reviewing, and testing TypeScript Hono apps, APIs, routers, middleware, validation, runtime adapters, error handling, and RPC-friendly clients. Use when working with Hono route handlers, app.route modules, hono/factory, hono/client hc, HonoRequest or Context APIs, Hono middleware, Cloudflare Workers or other Hono runtimes, or Hono test helpers.

- Skill: `significant-gravitas/hono` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add significant-gravitas/hono`
- Raw SKILL.md: https://api.skillmd.com/api/skills/significant-gravitas/hono/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Significant-Gravitas (https://skillmd.com/u/significant-gravitas)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/significant-gravitas/hono

---


# Hono

## Operating Mode

Use this skill to keep Hono code small, type-safe, runtime-portable, and aligned with official Hono patterns.

Before changing code:
- Inspect the installed Hono version, package manager, runtime adapter, existing route layout, validation library, and test setup.
- Read Hono types from `node_modules` when unsure about an API. Do not guess external API types.
- Prefer existing project conventions over introducing a new Hono architecture.
- If the user asks for the latest behavior or an unfamiliar Hono API, check the official docs first.

## Best-Practice Defaults

Read `references/best-practices.md` when implementing or reviewing non-trivial Hono code.

Default to these choices:
- Define route handlers inline after concrete path definitions so path params, validation targets, and response types infer correctly.
- Split larger apps with small `new Hono()` route modules and mount them with `app.route()`.
- For RPC/client typing, chain route definitions into a declared `const route` or `const app` and export `type AppType = typeof route`.
- Use `createMiddleware()` or `createFactory()` from `hono/factory` for reusable typed middleware and shared `Env` setup.
- Model `Bindings` and `Variables` explicitly on `new Hono<Env>()`, factories, and middleware.
- Use validator middleware plus `c.req.valid()` for typed inputs instead of reparsing unchecked request data in handlers.
- Use Web Standard `Request` and `Response` behavior directly; avoid Node-specific assumptions unless the selected runtime is Node and the adapter supports them.
- Test with `app.request()` and pass mock `env` as the third argument when handlers depend on runtime bindings.

## Review Checklist

When reviewing Hono code, look first for:
- Controllers or extracted handlers that lost path-param or validation inference.
- Route modules mounted before their routes are registered.
- RPC types exported from an unchained app, a widened type, or the wrong route variable.
- Middleware ordering bugs, missing `await next()`, or middleware that unexpectedly early-returns.
- Context variables set without matching `Variables` typing.
- Unvalidated `await c.req.json()`, unchecked query parsing, or duplicated validation logic.
- Error handlers that assume global `onError()` responses are inferred by `hono/client` without `ApplyGlobalResponse`.
- Tests that bypass `app.request()` or fail to mock `c.env`/bindings.

## Source Map

Use official docs as the source of truth:
- Full docs for search: `https://hono.dev/llms-full.txt`
- Best practices: `https://hono.dev/docs/guides/best-practices`
- Middleware: `https://hono.dev/docs/guides/middleware`
- Validation: `https://hono.dev/docs/guides/validation`
- RPC: `https://hono.dev/docs/guides/rpc`
- Testing: `https://hono.dev/docs/guides/testing`
- Factory helper: `https://hono.dev/docs/helpers/factory`
- App API: `https://hono.dev/docs/api/hono/`
- Context API: `https://hono.dev/docs/api/context`
- Routing API: `https://hono.dev/api/routing`