hono-guide

Hono Coding Guidelines

Requirements

• Hono ≥ 4.0, @hono/node-server, @hono/zod-validator, TypeScript ≥ 5.8

Essentials

• Factory functions - Use for testability and domain organization, see references/application-structure.md
• Type-safe validation - Recover types at the c.req.valid boundary; schema design in zod-guide, see references/validation-type-safety.md
• Middleware configuration - Use factories for CORS, composition with some()/every()/except(), see references/middleware-patterns.md, references/middleware-combine.md
• WebSocket helpers - Keep object references to maintain this binding, see references/websocket-support.md
• Error responses - Use RFC 9457 Problem Details with application/problem+json, see references/error-handling.md
• Security middleware - Apply secureHeaders() for security headers, see references/security-middleware.md
• Cookie handling - Set secure options explicitly, use signed cookies, see references/cookie-handling.md
• Platform portability - Use env(c) for environment, getRuntimeKey() for detection, see references/platform-runtime.md

Example

import {Hono} from "hono";
import {secureHeaders} from "hono/secure-headers";

export function createApp() {
  const app = new Hono();
  app.use("*", secureHeaders());
  app.route("/api/v1", v1Router);
  return app;
}

Gotchas

• c.req.valid('json') is typed by inference only when zValidator is chained inline on the route; an imported base-Context controller sees any, so cast there, but that cast is unchecked and can hide schema drift
• Middleware runs in the order it's registered: auth before routes, error handlers last; ordering bugs cause silent 200s on protected routes
• env(c) is the portable way to read env vars across runtimes: process.env works on Node but not Workers/Deno
• WebSocket helpers capture this from the closing object: assigning the handler to a variable loses the binding