hono-ops

Files (20)

• SKILL.md
• hono-facts.json · assets/
• vitest.config.template.ts · assets/
• worker-template.ts · assets/
• app-composition.md · references/
• durable-objects.md · references/
• errors-validation.md · references/
• jsx-ssr.md · references/
• middleware.md · references/
• openapi.md · references/
• routing-and-request.md · references/
• rpc-clients.md · references/
• runtime-adapters.md · references/
• streaming-and-realtime.md · references/
• testing.md · references/
• workers-runtime.md · references/
• check-hono-facts.py · scripts/
• route-inventory.py · scripts/
• sample-app.ts · tests/fixtures/
• run.sh · tests/

SKILL.md (first lines)

# Hono Operations

Hono on Cloudflare Workers: composing multi-app APIs in one Worker, middleware
discipline, typed errors, validation at the HTTP boundary, SPA co-serving, RPC
clients, and testing under vitest-pool-workers. Patterns here are distilled from a
production multi-tenant Worker (one Hono app, 6+ mounted sub-apps, ~1350 tests).

> Verified against Hono v4 (2026). Workers-first; the Node/Bun/Deno deltas and
> porting checklist live in references/runtime-adapters.md.

**Staleness check:** `python scripts/check-hono-facts.py --offline` asserts the
version-bearing facts (Hono major, `@hono/zod-validator`,
`@cloudflare/vitest-pool-workers`) are still named in the prose and the dated
currency note above is present; `--live` confirms each package's npm major still
matches. Catalog: `assets/hono-facts.json`.

## Decision Tree

```
What are you doing with Hono?
│
├─ Structuring an app (generics, sub-apps, env typing)
│  └─ Below + references/app-composition.md
│
├─ Middleware (ordering, auth, headers, exclusion boundaries)
│  └─ Below + references/middleware.md
│
├─ Errors / 404s / request validation
│  └─ Below + references/errors-validation.md
│
├─ Path syntax, routers, c.req/c.res surface, cookies
│  └─ references/routing-and-request.md
│
├─ Serving a SPA / static assets from the same Worker
│  └─ references/workers-runtime.md
│
├─ Cron / queues alongside fetch; runtime gotchas
│  └─ references/workers-runtime.md
│
├─ Streaming / SSE / WebSockets / proxying / service bindings
│  └─ references/streaming-and-realtime.md
│
├─ Durable Objects (Hono in a DO, hibernated WS, alarms)
│  └─ references/durable-objects.md
│
├─ OpenAPI docs from routes (@hono/zod-openapi)
│  └─ references/openapi.md
│
├─ Server-rendered HTML / JSX / HTML emails
│  └─ references/jsx-ssr.md
│
├─ Running or porting to Node / Bun / Deno
│  └─ references/runtime-adapters.md
│
├─ Typed client (hc RPC vs hand-rolled)
│  └─ references/rpc-clients.md
│
├─ Testing (app.request, pool-workers, middleware isolation)
│  └─ references/testing.md + assets/vitest.config.template.ts
│
├─ Starting a new Worker from scratch
│  └─ assets/worker-template.ts (commented composition-root skeleton)
│
└─ Auditing an existing app's routes / middleware order
   └─ scripts/route-inventory.py (below)
```

## App Composition (the 80%)

Type the app once with `Bindings` (wrangler-provided env) and `Variables`
(per-request context you `c.set`):

```typescript
import { Hono } from 'hono';

interface Env {
  DB: D1Database;
  ASSETS: Fetcher;          // static assets binding (SPA)
  API_KEYS?: string;        // optional secret: gate features on presence, 503 when unset
}
type Vars = { identity: Identity; repo: ScopedRepository };

export const app = new Hono<{ Bindings: Env; Variables: Vars }>();
```

- `c.env.DB` — bindings, typed via `Bindings`.
- `c.set('identity', id)` / `c.get('identity')` / `c.var.identity` — per-request
  state, typed via `Variables`. Middleware writes it; handlers read it.
- Prefer the per-app `Variables` generic over global `ContextVariableMap`
  augmentation; the map is app-wide and leaks types across unrelated sub-apps
  (see [references/app-composition.md](references/app-composition.md)).

**Sub-app mounting** — one Worker, many feature apps, each its own file:

```typescript
// src/time/api.ts
export const timeApi = new Hono<{ Bindings: Env; Variables: Vars }>();
timeApi.get('/entries', (c) => { /* identity + repo already in context */ });

// src/index.ts — mounted under the auth middleware (see Middleware below)
app.route('/api/time', timeApi);       // timeApi sees paths relative to the mount
app.route('/api/time', billingApi);    // two sub-apps on one base is fine when
                                       // their paths are disjoint — Hono matches across both
```

The mounted sub-app inherits nothing implicitly except position: whatever
middleware was registered on a matching path *before* the mount runs first.
Position IS the security boundary — see Middleware.

## Middleware: Order Is the Contract

Hono middleware is an onion — code before `await next()` runs inbound, code
after runs outbound — and **registration order is matching order**. A middleware
registered after a matching handler never runs for it.

```typescript
app.use('*', securityHeaders());        // 1. outermost: response hardening
app.get('/api/health', (c) => c.json({ ok: true }));  // 2. before auth = unauthenticated

From 0xDarkMatter/claude-mods, MIT.

More from 0xDarkMatter/claude-mods