Hono on Cloudflare Workers: composing multi-app APIs in one Worker, middleware\ndiscipline, typed errors, validation at the HTTP boundary, SPA co-serving, RPC\nclients, and testing under vitest-pool-workers. Patterns here are distilled from a\nproduction multi-tenant Worker (one Hono app, 6+ mounted sub-apps, ~1350 tests).
\n\n\nVerified against Hono v4 (2026). Workers-first; the Node/Bun/Deno deltas and\nporting checklist live in references/runtime-adapters.md.
\n
Staleness check: python scripts/check-hono-facts.py --offline asserts the\nversion-bearing facts (Hono major, @hono/zod-validator,\n@cloudflare/vitest-pool-workers) are still named in the prose and the dated\ncurrency note above is present; --live confirms each package's npm major still\nmatches. Catalog: assets/hono-facts.json.
What are you doing with Hono?\n│\n├─ Structuring an app (generics, sub-apps, env typing)\n│ └─ Below + references/app-composition.md\n│\n├─ Middleware (ordering, auth, headers, exclusion boundaries)\n│ └─ Below + references/middleware.md\n│\n├─ Errors / 404s / request validation\n│ └─ Below + references/errors-validation.md\n│\n├─ Path syntax, routers, c.req/c.res surface, cookies\n│ └─ references/routing-and-request.md\n│\n├─ Serving a SPA / static assets from the same Worker\n│ └─ references/workers-runtime.md\n│\n├─ Cron / queues alongside fetch; runtime gotchas\n│ └─ references/workers-runtime.md\n│\n├─ Streaming / SSE / WebSockets / proxying / service bindings\n│ └─ references/streaming-and-realtime.md\n│\n├─ Durable Objects (Hono in a DO, hibernated WS, alarms)\n│ └─ references/durable-objects.md\n│\n├─ OpenAPI docs from routes (@hono/zod-openapi)\n│ └─ references/openapi.md\n│\n├─ Server-rendered HTML / JSX / HTML emails\n│ └─ references/jsx-ssr.md\n│\n├─ Running or porting to Node / Bun / Deno\n│ └─ references/runtime-adapters.md\n│\n├─ Typed client (hc RPC vs hand-rolled)\n│ └─ references/rpc-clients.md\n│\n├─ Testing (app.request, pool-workers, middleware isolation)\n│ └─ references/testing.md + assets/vitest.config.template.ts\n│\n├─ Starting a new Worker from scratch\n│ └─ assets/worker-template.ts (commented composition-root skeleton)\n│\n└─ Auditing an existing app's routes / middleware order\n └─ scripts/route-inventory.py (below)\nType the app once with Bindings (wrangler-provided env) and Variables\n(per-request context you c.set):
import { Hono } from 'hono';\n\ninterface Env {\n DB: D1Database;\n ASSETS: Fetcher; // static assets binding (SPA)\n API_KEYS?: string; // optional secret: gate features on presence, 503 when unset\n}\ntype Vars = { identity: Identity; repo: ScopedRepository };\n\nexport const app = new Hono<{ Bindings: Env; Variables: Vars }>();\nc.env.DB — bindings, typed via Bindings.c.set('identity', id) / c.get('identity') / c.var.identity — per-request\nstate, typed via Variables. Middleware writes it; handlers read it.Variables generic over global ContextVariableMap\naugmentation; the map is app-wide and leaks types across unrelated sub-apps\n(see references/app-composition.md).Sub-app mounting — one Worker, many feature apps, each its own file:
\n// src/time/api.ts\nexport const timeApi = new Hono<{ Bindings: Env; Variables: Vars }>();\ntimeApi.get('/entries', (c) => { /* identity + repo already in context */ });\n\n// src/index.ts — mounted under the auth middleware (see Middleware below)\napp.route('/api/time', timeApi); // timeApi sees paths relative to the mount\napp.route('/api/time', billingApi); // two sub-apps on one base is fine when\n // their paths are disjoint — Hono matches across both\nThe mounted sub-app inherits nothing implicitly except position: whatever\nmiddleware was registered on a matching path before the mount runs first.\nPosition IS the security boundary — see Middleware.
\nHono middleware is an onion — code before await next() runs inbound, code\nafter runs outbound — and registration order is matching order. A middleware\nregistered after a matching handler never runs for it.
app.use('*', securityHeaders()); // 1. outermost: response hardening\napp.get('/api/health', (c) => c.json({ ok: true })); // 2. before auth = unauthenticated\n\napp.use('/api/*', async (c, next) => { // 3. auth: verify, then stash identity\n if (c.req.path === '/api/health') return next(); // skip-list for exceptions\n const user = await verifyAndResolve(c.req.raw, c.env); // throws/403s on failure\n if (!user) return c.json({ error: 'forbidden' }, 403);\n c.set('identity', user);\n c.set('repo', scopedRepo(c.env.DB, user)); // handlers never touch raw bindings\n await next();\n});\n\napp.route('/api/time', timeApi); // 4. inside the auth boundary\napp.route('/vesper', vesper); // 5. OUTSIDE /api/* — bearer-key auth, on purpose\napp.route('/ingest', ingest); // machine-to-machine, own auth in the sub-app\n\napp.all('/api/*', (c) => c.json({ error: 'not_found' }, 404)); // JSON 404 for API\napp.all('*', (c) => c.env.ASSETS.fetch(c.req.raw)); // SPA fallback, LAST\nTwo load-bearing rules:
\nc.get(...) and can't reach\nunscoped resources by construction./vesper, /ingest/* above), each carrying its own auth middleware.\nDon't punch exemptions through session auth with flags — move the mount.Depth (skip-lists vs path shape, security headers + the immutable-headers trap,\ntiming-safe bearer compare): references/middleware.md.
\nThrow typed errors anywhere below the handler; map them to HTTP in exactly one\nplace:
\nexport class AppError extends Error {\n constructor(public readonly status: number, public readonly code: string, message: string) {\n super(message); this.name = 'AppError';\n }\n}\nexport const NotFound = (m = 'not found') => new AppError(404, 'not_found', m);\nexport const Forbidden = (m = 'forbidden') => new AppError(403, 'forbidden', m);\nexport const Conflict = (m = 'version conflict, reload and retry') => new AppError(409, 'conflict', m);\n\napp.onError((err, c) => {\n if (err instanceof AppError) return c.json({ error: err.code, message: err.message }, err.status as 400);\n if (err instanceof SyntaxError) return c.json({ error: 'bad_request', message: 'invalid JSON body' }, 400);\n console.error('unhandled error', err); // log the real thing…\n return c.json({ error: 'internal' }, 500); // …never leak it to the wire\n});\n/api/* gets a JSON 404; everything else falls through to the SPA\nshell. Never let an API typo return index.html.app.notFound() exists but only fires when nothing matched — with a\ncatch-all SPA route it never runs; use the explicit two-route split above.Validation at the boundary (zValidator vs hand-rolled assertions, and when each\nwins): references/errors-validation.md.
\napp.request() / app.fetch() run the real app — middleware, routing, errors —\nwith no server:
import { env } from 'cloudflare:test'; // vitest-pool-workers: real bindings\nimport { app } from '../src/index';\n\nconst res = await app.request('/api/health', {}, env); // env = 3rd arg (Bindings)\nexpect(res.status).toBe(200);\nUnder @cloudflare/vitest-pool-workers the test runs inside workerd with real\nD1/KV/R2 bindings from defineWorkersConfig. Full setup — migrations into the\ntest DB, isolated storage, an Access-JWT signing harness, testing one middleware\nin isolation, and the workerd-version-lag trap:\nreferences/testing.md.
scripts/route-inventory.py statically scans a Hono TypeScript source tree and\nlists every route, middleware registration, and app.route() mount with\nfile:line — plus --check, three registration-order lints (every finding is\na consequence of Hono matching in registration order):
(method, path) registered twice (the second is dead)# Inventory a Worker's HTTP surface (TSV: kind, method, path, file:line)\npython skills/hono-ops/scripts/route-inventory.py src/\n\n# JSON envelope for downstream tooling\npython skills/hono-ops/scripts/route-inventory.py --json src/ | jq '.data[] | select(.kind==\"mount\")'\n\n# Lint registration order: exit 10 = findings (each carries an `issue` field in --json)\npython skills/hono-ops/scripts/route-inventory.py --check src/\nExit codes: 0 clean, 2 usage, 3 path not found, 10 findings\n(--check). Regex-based on purpose — it needs no TypeScript compiler API and\nworks on any checkout.
| Gotcha | \nWhy | \nFix | \n
|---|---|---|
| \"Illegal invocation\" on fetch | \nCalling this.fetchImpl(...) binds this to your object; global fetch requires no receiver | \nDetach first: const doFetch = this.fetchImpl; await doFetch(url, ...) | \n
Mutating ASSETS.fetch response headers throws | \nAny fetch()-derived Response has immutable headers in workerd | \nRebuild: new Response(res.body, { status, headers: new Headers(res.headers) }) | \n
caches API \"cache\" misses constantly | \nIt's per-colo, not global — every PoP has its own | \nTreat as a short-TTL local collapse (poll-storm absorber), never as KV | \n
waitUntil work vanishes | \nPost-response work must be registered before the handler returns; unregistered promises are cancelled | \nc.executionCtx.waitUntil(promise) inside the handler | \n
| Middleware doesn't run for a route | \nRegistered after the handler — order is matching order | \nRegister middleware first; verify with route-inventory.py --check | \n
wrangler dev host surprises | \nDev rewrites the request host to the [[routes]] pattern | \nPin [dev] host in wrangler config when auth branches on hostname | \n
| Optional secret unset | \nRoute depends on an env secret that isn't configured | \nGate on presence: if (!c.env.KEY) return c.json({ error: 'unavailable' }, 503) | \n
More depth (SPA assets config, run_worker_first, scheduled/queue handlers,\nper-cron branching): references/workers-runtime.md.
| Reference | \nWhen to Load | \n
|---|---|
| references/app-composition.md | \nGenerics (Bindings/Variables), ContextVariableMap trade-offs, sub-app mounting semantics, basePath, env-shape design | \n
| references/middleware.md | \nOnion model, ordering proofs, auth middleware that builds context, security headers, bearer-auth sub-apps outside the session boundary | \n
| references/errors-validation.md | \nonError mapping, typed error classes, 404 strategy, zValidator vs hand-rolled validation trade-offs | \n
| references/routing-and-request.md | \nRouter internals, path syntax (params/regex/optional/wildcards), matching precedence, c.req/response helpers, cookies (incl. signed), JSX/html | \n
| references/testing.md | \napp.request() patterns, vitest-pool-workers config (D1 migrations, bindings, isolation), JWT test harness, middleware-in-isolation | \n
| references/rpc-clients.md | \nhc<AppType> RPC client, chained-route inference requirement, when a hand-rolled typed client is the better call | \n
| references/workers-runtime.md | \nSPA/static assets from one Worker, scheduled() + queue handlers beside fetch, waitUntil, caches, detached fetch | \n
| references/streaming-and-realtime.md | \nstream/streamText/streamSSE, WebSockets (plain Worker vs Durable Object hibernation), proxying, service bindings | \n
| references/durable-objects.md | \nRouting into DOs, a Hono app per object, hibernated WebSockets, alarms, Hono-in-DO vs RPC methods | \n
| references/openapi.md | \n@hono/zod-openapi schema-first routes, swagger/Scalar UI, hono-openapi annotations, when to skip OpenAPI entirely | \n
| references/jsx-ssr.md | \nhono/jsx server rendering, jsxRenderer layouts, async components + Suspense streaming, raw() escaping rules, the SPA-scope guard (HonoX ladder) | \n
| references/runtime-adapters.md | \nNode (@hono/node-server) / Bun / Deno deltas — env, static files, WebSockets, cron — plus the Workers→Node porting checklist | \n
Starter assets:
\nonError, cron) with adapt-points marked. Copy it\nas the seed of a new Worker.cloudflare-ops — wrangler config, bindings provisioning, deploy/CIsqlite-ops — D1 specifics (sessions/bookmarks, batch semantics, query plans)typescript-ops — generics, Zod 4, type-narrowing the payloads you validaterest-ops / api-design-ops — endpoint and contract design above the frameworkauth-ops — JWT/session/token theory behind the auth middleware patterns