Hono Idioms

Hono Idioms and Patterns

Core Philosophy

Hono rewards thin handlers, middleware composition, multi-runtime portability, and end-to-end type safety. Idiomatic Hono = typed routes, validator middleware, RPC client — no code generation needed.

Scope: Hono-specific patterns. For TypeScript fundamentals: @.agents/skills/typescript-idioms/SKILL.md. For project structure: @.agents/skills/hono-idioms/references/project-structure.md.

Loading guard / auto-detection: Hono has no canonical marker file, so it is not reliably auto-detected by file glob (only wrangler.toml — the Cloudflare Workers case — triggers this skill directly). For Node.js / Bun / Deno Hono projects, co-load this skill alongside @.agents/skills/typescript-idioms/SKILL.md whenever hono appears in package.json. Do NOT load this skill for Express, Fastify, or NestJS — it is Hono-only.

When to Load References

Load these before writing code in the matching context — not after.

Router and Route Organization

1. Create apps with new Hono() and method routing:

   // ✅ Group by resource, compose with app.route()
   const tasks = new Hono()
       .get('/', listTasks)
       .post('/', createTask)
       .get('/:id', getTask)
       .put('/:id', updateTask)
       .delete('/:id', deleteTask);
   
   const app = new Hono()
       .route('/api/tasks', tasks)
       .route('/api/users', users);

2. Use app.route('/prefix', subApp) to compose sub-routers — each feature exports its own Hono instance.

3. app.basePath('/api/v1') for API versioning — applied once at root level.

4. app.all('*', handler) for catch-all fallback routes.

5. Path parameters use :name syntax — accessed via c.req.param('name').

Context (c)

1. Response helpers — always use typed helpers, never raw Response:

   // ✅ c.json(), c.text(), c.html(), c.redirect(), c.notFound()
   app.get('/tasks/:id', async (c) => {
       const task = await taskService.find(c.req.param('id'));
       return c.json(task);
   });

2. Request data: c.req.param('id') (path), c.req.query('page') (query string), c.req.header('Authorization') (header), await c.req.json() (body — prefer zValidator instead).

3. Request-scoped typed variables with c.set() / c.get():

   type Env = { Variables: { userId: string; requestId: string } };
   const app = new Hono<Env>();
   
   app.use(async (c, next) => {
       c.set('requestId', crypto.randomUUID());
       await next();
   });
   app.get('/me', (c) => c.json({ id: c.get('userId') })); // fully typed

Middleware

1. Built-in middleware — cors(), logger(), secureHeaders(), compress(), timing(), prettyJSON() (each imported from hono/<name>):

   app.use('*', logger(), secureHeaders(), compress());

2. Global vs scoped middleware:

   // ✅ Global — applies to all routes
   app.use('*', cors());
   
   // ✅ Scoped — applies only to /api/* routes
   app.use('/api/*', authMiddleware);

3. Custom middleware with createMiddleware<>():

   import { createMiddleware } from 'hono/factory';
   
   type AuthEnv = { Variables: { userId: string } };
   
   const authMiddleware = createMiddleware<AuthEnv>(async (c, next) => {
       const token = c.req.header('Authorization')?.replace('Bearer ', '');
       if (!token) throw new HTTPException(401, { message: 'Unauthorized' });
       const payload = await verifyToken(token);
       c.set('userId', payload.sub);
       await next();
   });

4. Middleware ordering matters — auth before route handlers, logging outermost.

Validation

1. @hono/zod-validator for type-safe request validation:

   import { zValidator } from '@hono/zod-validator';
   import { z } from 'zod';
   
   const CreateTaskSchema = z.object({
       title: z.string().min(1).max(200),
       priority: z.enum(['low', 'medium', 'high']),
   });
   
   // ✅ Compose multiple validators — validated data is fully typed
   app.post('/tasks', zValidator('json', CreateTaskSchema), async (c) => {
       const body = c.req.valid('json');   // { title: string; priority: 'low'|'medium'|'high' }
       const task = await taskService.create(body);
       return c.json(task, 201);
   });
   
   app.get('/tasks/:id', zValidator('param', z.object({ id: z.string().uuid() })), async (c) => {
       const task = await taskService.find(c.req.valid('param').id);
       return c.json(task);
   });

2. Validate all input sources: zValidator('json', ...), zValidator('param', ...), zValidator('query', ...), zValidator('header', ...).

Error Handling

1. app.onError() for global error handling:

   import { HTTPException } from 'hono/http-exception';
   
   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);
   });

2. HTTPException for typed HTTP errors:

   // ✅ Throw in handlers or middleware — caught by onError
   if (!task) throw new HTTPException(404, { message: `Task ${id} not found` });

3. app.notFound() for custom 404 handling:

   app.notFound((c) => c.json({ error: 'Not Found' }, 404));

RPC Client

1. End-to-end type-safe API calls — no code generation:

   // server.ts — chain routes and export the type
   const routes = app
       .get('/tasks', async (c) => c.json(await taskService.list()))
       .post('/tasks', zValidator('json', CreateTaskSchema), async (c) => {
           return c.json(await taskService.create(c.req.valid('json')), 201);
       });
   export type AppType = typeof routes;
   
   // client.ts — fully typed, changes propagate compile errors automatically
   import { hc } from 'hono/client';
   import type { AppType } from './server';
   const client = hc<AppType>('http://localhost:3000');
   const res = await client.tasks.$post({ json: { title: 'New', priority: 'high' } });
   const task = await res.json(); // fully typed