hono-patterns

license	Apache-2.0
name	hono-patterns
allowed-tools	Read,Write,Edit,Bash,Glob,Grep,WebSearch,WebFetch
description	Use when building APIs on Hono (Cloudflare Workers, Bun, Deno, Node), debugging route ordering, wiring middleware, validating with @hono/zod-validator, returning streaming responses, configuring CORS with credentials, handling errors via app.onError, or composing typed RPC clients. Triggers: c.env binding types, c.header + c.redirect interaction, missing await next() bugs, Set-Cookie not attaching to redirect, route-precedence surprises, JWT middleware setup, hono/client typed RPC end-to-end. NOT for Express/Fastify/Koa idioms, tRPC/GraphQL paradigms, or Next.js Route Handlers.
metadata	{"category":"Backend & Infrastructure","tags":["hono","cloudflare-workers","bun","edge","middleware","typescript"],"provenance":{"kind":"first-party","owners":["port-daddy"]},"pairs-with":[{"skill":"htmx-progressive-enhancement","reason":"Hono is a natural server for htmx -- routes return HTML fragments and the HX-Request header decides fragment vs full page"},{"skill":"websocket-realtime-expert","reason":"Long-lived WebSocket/SSE connections behind Hono routes need the realtime design (backpressure, reconnect) this skill does not cover"},{"skill":"error-handling-patterns","reason":"app.onError is the framework hook; what a sanitized, typed error taxonomy looks like is the paired skill's domain"}],"io-contract":{"kind":"deliverable","consumes":["[Truncated]","[Truncated]"],"produces":["[Truncated]","[Truncated]"]}}

Hono Patterns

Hono is a small router with a strong middleware model and ergonomic typing. Most surprises come from middleware ordering, deferred header semantics, and the c.env/Variables generic dance.

When to use

• Designing an API on Workers, Bun, or Deno where Express would be overkill.
• Type-safe end-to-end RPC client (hono/client).
• Streaming SSE / NDJSON responses.
• A redirect-driven login flow where Set-Cookie must attach to the response.
• CORS with credentials, where * won't work.
• Custom error responses through app.onError.

Core capabilities

The Hono generic — typed bindings and locals

type Bindings = {
  DB: D1Database;
  KV: KVNamespace;
  WINDAGS_INTERNAL_TOKEN: string;
};

type Variables = {
  user: { id: string; role: 'admin' | 'member' };
  startedAt: number;
};

const app = new Hono<{ Bindings: Bindings; Variables: Variables }>();

Now c.env.DB is typed D1Database; c.var.user is typed; c.set('user', …) and c.get('user') are checked.

Route ordering

Hono matches in registration order. Specific before wildcard:

app.get('/v1/skills/search', searchHandler);   // specific
app.(, getOneHandler);      
app.(, fallback);