Claude Skill

hono-ops

Hono on Cloudflare Workers - composition, middleware, typed bindings, validation, RPC, streaming, testing. Use for: hono, hono middleware, app.route, hono rpc, c.env bindings, onError, zValidator, vitest-pool-workers, spa fallback worker.

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download 0xDarkMatter-claude-mods-skills_hono-ops-6aef525.zip · 58 KB

Install

skills CLI npx skills add https://github.com/0xDarkMatter/claude-mods/tree/main/skills/hono-ops
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install 0xdarkmatter-claude-mods@llmmart
Git git clone https://github.com/0xDarkMatter/claude-mods.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole 0xdarkmatter/claude-mods collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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):

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).

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

// 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.

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

app.use('/api/*', async (c, next) => {  // 3. auth: verify, then stash identity
  if (c.req.path === '/api/health') return next();   // skip-list for exceptions
  const user = await verifyAndResolve(c.req.raw, c.env);   // throws/403s on failure
  if (!user) return c.json({ error: 'forbidden' }, 403);
  c.set('identity', user);
  c.set('repo', scopedRepo(c.env.DB, user));  // handlers never touch raw bindings
  await next();
});

app.route('/api/time', timeApi);        // 4. inside the auth boundary
app.route('/vesper', vesper);           // 5. OUTSIDE /api/* — bearer-key auth, on purpose
app.route('/ingest', ingest);           // machine-to-machine, own auth in the sub-app

app.all('/api/*', (c) => c.json({ error: 'not_found' }, 404));  // JSON 404 for API
app.all('*', (c) => c.env.ASSETS.fetch(c.req.raw));             // SPA fallback, LAST

Two load-bearing rules:

  1. Auth middleware verifies, then builds the request's whole world (identity, scoped repo/session) into context. Handlers read c.get(...) and can't reach unscoped resources by construction.
  2. Routes with a different auth model mount OUTSIDE the middleware's path pattern (/vesper, /ingest/* above), each carrying its own auth middleware. Don't punch exemptions through session auth with flags — move the mount.

Depth (skip-lists vs path shape, security headers + the immutable-headers trap, timing-safe bearer compare): references/middleware.md.

Errors: One Typed Boundary

Throw typed errors anywhere below the handler; map them to HTTP in exactly one place:

export class AppError extends Error {
  constructor(public readonly status: number, public readonly code: string, message: string) {
    super(message); this.name = 'AppError';
  }
}
export const NotFound  = (m = 'not found')  => new AppError(404, 'not_found', m);
export const Forbidden = (m = 'forbidden')  => new AppError(403, 'forbidden', m);
export const Conflict  = (m = 'version conflict, reload and retry') => new AppError(409, 'conflict', m);

app.onError((err, c) => {
  if (err instanceof AppError)    return c.json({ error: err.code, message: err.message }, err.status as 400);
  if (err instanceof SyntaxError) return c.json({ error: 'bad_request', message: 'invalid JSON body' }, 400);
  console.error('unhandled error', err);          // log the real thing…
  return c.json({ error: 'internal' }, 500);      // …never leak it to the wire
});
  • Cross-scope access returns 404, not 403 — a 403 confirms the row exists in someone else's scope.
  • Unmatched /api/* gets a JSON 404; everything else falls through to the SPA shell. Never let an API typo return index.html.
  • app.notFound() exists but only fires when nothing matched — with a catch-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 wins): references/errors-validation.md.

Testing Quickstart

app.request() / app.fetch() run the real app — middleware, routing, errors — with no server:

import { env } from 'cloudflare:test';   // vitest-pool-workers: real bindings
import { app } from '../src/index';

const res = await app.request('/api/health', {}, env);   // env = 3rd arg (Bindings)
expect(res.status).toBe(200);

Under @cloudflare/vitest-pool-workers the test runs inside workerd with real D1/KV/R2 bindings from defineWorkersConfig. Full setup — migrations into the test DB, isolated storage, an Access-JWT signing harness, testing one middleware in isolation, and the workerd-version-lag trap: references/testing.md.

Route Inventory Script

scripts/route-inventory.py statically scans a Hono TypeScript source tree and lists every route, middleware registration, and app.route() mount with file:line — plus --check, three registration-order lints (every finding is a consequence of Hono matching in registration order):

  • bypass — a route registered before a middleware whose pattern covers it (it silently skips that middleware: the #1 Hono ordering bug)
  • duplicate — the same (method, path) registered twice (the second is dead)
  • shadowed — a route after an earlier broader same-method route (never matches)
# Inventory a Worker's HTTP surface (TSV: kind, method, path, file:line)
python skills/hono-ops/scripts/route-inventory.py src/

# JSON envelope for downstream tooling
python skills/hono-ops/scripts/route-inventory.py --json src/ | jq '.data[] | select(.kind=="mount")'

# Lint registration order: exit 10 = findings (each carries an `issue` field in --json)
python skills/hono-ops/scripts/route-inventory.py --check src/

Exit codes: 0 clean, 2 usage, 3 path not found, 10 findings (--check). Regex-based on purpose — it needs no TypeScript compiler API and works on any checkout.

Gotchas (Workers-Specific)

Gotcha Why Fix
"Illegal invocation" on fetch Calling this.fetchImpl(...) binds this to your object; global fetch requires no receiver Detach first: const doFetch = this.fetchImpl; await doFetch(url, ...)
Mutating ASSETS.fetch response headers throws Any fetch()-derived Response has immutable headers in workerd Rebuild: new Response(res.body, { status, headers: new Headers(res.headers) })
caches API "cache" misses constantly It's per-colo, not global — every PoP has its own Treat as a short-TTL local collapse (poll-storm absorber), never as KV
waitUntil work vanishes Post-response work must be registered before the handler returns; unregistered promises are cancelled c.executionCtx.waitUntil(promise) inside the handler
Middleware doesn't run for a route Registered after the handler — order is matching order Register middleware first; verify with route-inventory.py --check
wrangler dev host surprises Dev rewrites the request host to the [[routes]] pattern Pin [dev] host in wrangler config when auth branches on hostname
Optional secret unset Route depends on an env secret that isn't configured Gate on presence: if (!c.env.KEY) return c.json({ error: 'unavailable' }, 503)

More depth (SPA assets config, run_worker_first, scheduled/queue handlers, per-cron branching): references/workers-runtime.md.

Reference Files

Reference When to Load
references/app-composition.md Generics (Bindings/Variables), ContextVariableMap trade-offs, sub-app mounting semantics, basePath, env-shape design
references/middleware.md Onion model, ordering proofs, auth middleware that builds context, security headers, bearer-auth sub-apps outside the session boundary
references/errors-validation.md onError mapping, typed error classes, 404 strategy, zValidator vs hand-rolled validation trade-offs
references/routing-and-request.md Router internals, path syntax (params/regex/optional/wildcards), matching precedence, c.req/response helpers, cookies (incl. signed), JSX/html
references/testing.md app.request() patterns, vitest-pool-workers config (D1 migrations, bindings, isolation), JWT test harness, middleware-in-isolation
references/rpc-clients.md hc<AppType> RPC client, chained-route inference requirement, when a hand-rolled typed client is the better call
references/workers-runtime.md SPA/static assets from one Worker, scheduled() + queue handlers beside fetch, waitUntil, caches, detached fetch
references/streaming-and-realtime.md stream/streamText/streamSSE, WebSockets (plain Worker vs Durable Object hibernation), proxying, service bindings
references/durable-objects.md Routing into DOs, a Hono app per object, hibernated WebSockets, alarms, Hono-in-DO vs RPC methods
references/openapi.md @hono/zod-openapi schema-first routes, swagger/Scalar UI, hono-openapi annotations, when to skip OpenAPI entirely
references/jsx-ssr.md hono/jsx server rendering, jsxRenderer layouts, async components + Suspense streaming, raw() escaping rules, the SPA-scope guard (HonoX ladder)
references/runtime-adapters.md Node (@hono/node-server) / Bun / Deno deltas — env, static files, WebSockets, cron — plus the Workers→Node porting checklist

Starter assets:

  • assets/worker-template.ts — commented composition-root skeleton (typed env, security headers, auth middleware, bearer sub-app, 404 split, onError, cron) with adapt-points marked. Copy it as the seed of a new Worker.
  • assets/vitest.config.template.ts — vitest-pool-workers config (D1 migrations into the test DB, isolation, worktree excludes, the compatibility-date pin) ready to adapt.

See Also

  • cloudflare-ops — wrangler config, bindings provisioning, deploy/CI
  • sqlite-ops — D1 specifics (sessions/bookmarks, batch semantics, query plans)
  • typescript-ops — generics, Zod 4, type-narrowing the payloads you validate
  • rest-ops / api-design-ops — endpoint and contract design above the framework
  • auth-ops — JWT/session/token theory behind the auth middleware patterns
  • test-engineering — which route tests catch real bugs, and running only the ones a change touches
Files (claude-mods)
  • assets
    • hono-facts.json 883 B
      Loading…
    • vitest.config.template.ts 2.9 KB
      Loading…
    • worker-template.ts 5.8 KB
      Loading…
  • references
    • app-composition.md 5.8 KB
      Loading…
    • durable-objects.md 4.9 KB
      Loading…
    • errors-validation.md 6.9 KB
      Loading…
    • jsx-ssr.md 5.3 KB
      Loading…
    • middleware.md 9.8 KB
      Loading…
    • openapi.md 3.7 KB
      Loading…
    • routing-and-request.md 6 KB
      Loading…
    • rpc-clients.md 6 KB
      Loading…
    • runtime-adapters.md 4.9 KB
      Loading…
    • streaming-and-realtime.md 5.7 KB
      Loading…
    • testing.md 7.4 KB
      Loading…
    • workers-runtime.md 7.1 KB
      Loading…
  • scripts
    • check-hono-facts.py 10 KB
      Loading…
    • route-inventory.py 11.4 KB
      Loading…
  • tests
    • fixtures
      • sample-app.ts 1.9 KB
        Loading…
    • run.sh 8.1 KB
      Loading…
  • SKILL.md 14.6 KB
    ---
    name: hono-ops
    description: "Hono on Cloudflare Workers - composition, middleware, typed bindings, validation, RPC, streaming, testing. Use for: hono, hono middleware, app.route, hono rpc, c.env bindings, onError, zValidator, vitest-pool-workers, spa fallback worker."
    license: MIT
    allowed-tools: "Read Write Bash Grep Glob"
    metadata:
      author: claude-mods
      related-skills: "cloudflare-ops, typescript-ops, sqlite-ops, rest-ops, test-engineering, auth-ops"
    ---
    
    # 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
    
    app.use('/api/*', async (c, next) => {  // 3. auth: verify, then stash identity
      if (c.req.path === '/api/health') return next();   // skip-list for exceptions
      const user = await verifyAndResolve(c.req.raw, c.env);   // throws/403s on failure
      if (!user) return c.json({ error: 'forbidden' }, 403);
      c.set('identity', user);
      c.set('repo', scopedRepo(c.env.DB, user));  // handlers never touch raw bindings
      await next();
    });
    
    app.route('/api/time', timeApi);        // 4. inside the auth boundary
    app.route('/vesper', vesper);           // 5. OUTSIDE /api/* — bearer-key auth, on purpose
    app.route('/ingest', ingest);           // machine-to-machine, own auth in the sub-app
    
    app.all('/api/*', (c) => c.json({ error: 'not_found' }, 404));  // JSON 404 for API
    app.all('*', (c) => c.env.ASSETS.fetch(c.req.raw));             // SPA fallback, LAST
    ```
    
    Two load-bearing rules:
    
    1. **Auth middleware verifies, then builds the request's whole world** (identity,
       scoped repo/session) into context. Handlers read `c.get(...)` and can't reach
       unscoped resources by construction.
    2. **Routes with a different auth model mount OUTSIDE the middleware's path
       pattern** (`/vesper`, `/ingest/*` above), each carrying its own auth middleware.
       Don't punch exemptions through session auth with flags — move the mount.
    
    Depth (skip-lists vs path shape, security headers + the immutable-headers trap,
    timing-safe bearer compare): [references/middleware.md](references/middleware.md).
    
    ## Errors: One Typed Boundary
    
    Throw typed errors anywhere below the handler; map them to HTTP in exactly one
    place:
    
    ```typescript
    export class AppError extends Error {
      constructor(public readonly status: number, public readonly code: string, message: string) {
        super(message); this.name = 'AppError';
      }
    }
    export const NotFound  = (m = 'not found')  => new AppError(404, 'not_found', m);
    export const Forbidden = (m = 'forbidden')  => new AppError(403, 'forbidden', m);
    export const Conflict  = (m = 'version conflict, reload and retry') => new AppError(409, 'conflict', m);
    
    app.onError((err, c) => {
      if (err instanceof AppError)    return c.json({ error: err.code, message: err.message }, err.status as 400);
      if (err instanceof SyntaxError) return c.json({ error: 'bad_request', message: 'invalid JSON body' }, 400);
      console.error('unhandled error', err);          // log the real thing…
      return c.json({ error: 'internal' }, 500);      // …never leak it to the wire
    });
    ```
    
    - Cross-scope access returns **404, not 403** — a 403 confirms the row exists in
      someone else's scope.
    - Unmatched `/api/*` gets a JSON 404; everything else falls through to the SPA
      shell. Never let an API typo return `index.html`.
    - `app.notFound()` exists but only fires when *nothing* matched — with a
      catch-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
    wins): [references/errors-validation.md](references/errors-validation.md).
    
    ## Testing Quickstart
    
    `app.request()` / `app.fetch()` run the real app — middleware, routing, errors —
    with no server:
    
    ```typescript
    import { env } from 'cloudflare:test';   // vitest-pool-workers: real bindings
    import { app } from '../src/index';
    
    const res = await app.request('/api/health', {}, env);   // env = 3rd arg (Bindings)
    expect(res.status).toBe(200);
    ```
    
    Under `@cloudflare/vitest-pool-workers` the test runs inside workerd with real
    D1/KV/R2 bindings from `defineWorkersConfig`. Full setup — migrations into the
    test DB, isolated storage, an Access-JWT signing harness, testing one middleware
    in isolation, and the workerd-version-lag trap:
    [references/testing.md](references/testing.md).
    
    ## Route Inventory Script
    
    `scripts/route-inventory.py` statically scans a Hono TypeScript source tree and
    lists every route, middleware registration, and `app.route()` mount with
    `file:line` — plus `--check`, three registration-order lints (every finding is
    a consequence of Hono matching in registration order):
    
    - **bypass** — a route registered *before* a middleware whose pattern covers it
      (it silently skips that middleware: the #1 Hono ordering bug)
    - **duplicate** — the same `(method, path)` registered twice (the second is dead)
    - **shadowed** — a route after an earlier broader same-method route (never matches)
    
    ```bash
    # Inventory a Worker's HTTP surface (TSV: kind, method, path, file:line)
    python skills/hono-ops/scripts/route-inventory.py src/
    
    # JSON envelope for downstream tooling
    python skills/hono-ops/scripts/route-inventory.py --json src/ | jq '.data[] | select(.kind=="mount")'
    
    # Lint registration order: exit 10 = findings (each carries an `issue` field in --json)
    python skills/hono-ops/scripts/route-inventory.py --check src/
    ```
    
    Exit codes: `0` clean, `2` usage, `3` path not found, `10` findings
    (`--check`). Regex-based on purpose — it needs no TypeScript compiler API and
    works on any checkout.
    
    ## Gotchas (Workers-Specific)
    
    | Gotcha | Why | Fix |
    |---|---|---|
    | "Illegal invocation" on fetch | Calling `this.fetchImpl(...)` binds `this` to your object; global fetch requires no receiver | Detach first: `const doFetch = this.fetchImpl; await doFetch(url, ...)` |
    | Mutating `ASSETS.fetch` response headers throws | Any `fetch()`-derived Response has immutable headers in workerd | Rebuild: `new Response(res.body, { status, headers: new Headers(res.headers) })` |
    | `caches` API "cache" misses constantly | It's per-colo, not global — every PoP has its own | Treat as a short-TTL local collapse (poll-storm absorber), never as KV |
    | `waitUntil` work vanishes | Post-response work must be registered before the handler returns; unregistered promises are cancelled | `c.executionCtx.waitUntil(promise)` inside the handler |
    | Middleware doesn't run for a route | Registered after the handler — order is matching order | Register middleware first; verify with `route-inventory.py --check` |
    | `wrangler dev` host surprises | Dev rewrites the request host to the `[[routes]]` pattern | Pin `[dev] host` in wrangler config when auth branches on hostname |
    | Optional secret unset | Route depends on an env secret that isn't configured | Gate on presence: `if (!c.env.KEY) return c.json({ error: 'unavailable' }, 503)` |
    
    More depth (SPA assets config, `run_worker_first`, scheduled/queue handlers,
    per-cron branching): [references/workers-runtime.md](references/workers-runtime.md).
    
    ## Reference Files
    
    | Reference | When to Load |
    |-----------|-------------|
    | [references/app-composition.md](references/app-composition.md) | Generics (`Bindings`/`Variables`), `ContextVariableMap` trade-offs, sub-app mounting semantics, `basePath`, env-shape design |
    | [references/middleware.md](references/middleware.md) | Onion model, ordering proofs, auth middleware that builds context, security headers, bearer-auth sub-apps outside the session boundary |
    | [references/errors-validation.md](references/errors-validation.md) | `onError` mapping, typed error classes, 404 strategy, zValidator vs hand-rolled validation trade-offs |
    | [references/routing-and-request.md](references/routing-and-request.md) | Router internals, path syntax (params/regex/optional/wildcards), matching precedence, `c.req`/response helpers, cookies (incl. signed), JSX/html |
    | [references/testing.md](references/testing.md) | `app.request()` patterns, vitest-pool-workers config (D1 migrations, bindings, isolation), JWT test harness, middleware-in-isolation |
    | [references/rpc-clients.md](references/rpc-clients.md) | `hc<AppType>` RPC client, chained-route inference requirement, when a hand-rolled typed client is the better call |
    | [references/workers-runtime.md](references/workers-runtime.md) | SPA/static assets from one Worker, `scheduled()` + queue handlers beside `fetch`, `waitUntil`, `caches`, detached fetch |
    | [references/streaming-and-realtime.md](references/streaming-and-realtime.md) | `stream`/`streamText`/`streamSSE`, WebSockets (plain Worker vs Durable Object hibernation), proxying, service bindings |
    | [references/durable-objects.md](references/durable-objects.md) | Routing into DOs, a Hono app per object, hibernated WebSockets, alarms, Hono-in-DO vs RPC methods |
    | [references/openapi.md](references/openapi.md) | `@hono/zod-openapi` schema-first routes, swagger/Scalar UI, `hono-openapi` annotations, when to skip OpenAPI entirely |
    | [references/jsx-ssr.md](references/jsx-ssr.md) | `hono/jsx` server rendering, `jsxRenderer` layouts, async components + Suspense streaming, `raw()` escaping rules, the SPA-scope guard (HonoX ladder) |
    | [references/runtime-adapters.md](references/runtime-adapters.md) | Node (`@hono/node-server`) / Bun / Deno deltas — env, static files, WebSockets, cron — plus the Workers→Node porting checklist |
    
    **Starter assets:**
    
    - [assets/worker-template.ts](assets/worker-template.ts) — commented
      composition-root skeleton (typed env, security headers, auth middleware,
      bearer sub-app, 404 split, `onError`, cron) with adapt-points marked. Copy it
      as the seed of a new Worker.
    - [assets/vitest.config.template.ts](assets/vitest.config.template.ts) —
      vitest-pool-workers config (D1 migrations into the test DB, isolation,
      worktree excludes, the compatibility-date pin) ready to adapt.
    
    ## See Also
    
    - `cloudflare-ops` — wrangler config, bindings provisioning, deploy/CI
    - `sqlite-ops` — D1 specifics (sessions/bookmarks, batch semantics, query plans)
    - `typescript-ops` — generics, Zod 4, type-narrowing the payloads you validate
    - `rest-ops` / `api-design-ops` — endpoint and contract design above the framework
    - `auth-ops` — JWT/session/token theory behind the auth middleware patterns
    - `test-engineering` — which route tests catch real bugs, and running only the ones a change touches
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.