Hono 4 (Cloudflare)
Hono 4.x (TypeScript edge web framework) rules for Cursor. Pinned to hono ^4.12.19, @hono/zod-validator ^0.8.0, @hono/zod-openapi ^1.4.0 (zod ^4.x peer), @hono/node-server ^2.0.3 (Node 20+). Leads with v4-era APIs that pre-2025 LLMs miss: c.json() always returns TypedResponse (since v4.3.0), validator throws HTTPException instead of returning, getCookie/setCookie from hono/cookie (c.req.cookie removed), c.env property access (c.env() function removed), stream/streamText/streamSSE from hono/streaming (c.stream removed), showRoutes from hono/dev (app.showRoutes removed), getConnInfo helper for runtime IP, fire(app) from hono/service-worker (app.fire deprecated v4.8.0), Workers Static Assets binding (serveStatic from hono/cloudflare-workers deprecated v4.3.0), JSR @hono/hono on Deno (deno.land/x stale v4.4.0+), @hono/node-server v2 requires Node 20+. Catches 50+ regressions including Express-style res.json()/req.params/(req,res,next)/(err,req,res,next)/bodyParser leakage, npm cors over hono/cors, supertest over app.request, c.req.body over awaited c.req.json(), forgotten import type on hc<AppType> (the #1 RPC bundle-bloat pitfall), Rails-style controllers losing path-param type inference, exporting app before chain finishes (drops RPC types), zValidator placement after handler (TS error), c.notFound() breaking RPC type union, raw new Response() in handlers breaking RPC, relative URL passed to hc(), untyped c.userId = inline assignments (no Variables generic), c.executionCtx.waitUntil throwing on Bun, process.env in Workers (should be c.env), fs/path imports in Workers, node_compat vs nodejs_compat, missing waitUntil for fire-and-forget, unawaited c.env.DB.prepare().run(), no secureHeaders middleware, no csrf middleware on POST, cors origin '*' with credentials, missing bodyLimit + CVE-2025-59139, cookie missing httpOnly/secure/sameSite, SameSite=None without Secure, PII in logger, no etag/cache on GET, hard-coded JWT secret, JSON build in memory instead of streamSSE, sub-app notFound that never fires, trailing-slash inconsistency, double next() call, basePath used as statement, throw redirect/throw error patterns leaking from SvelteKit prompts, Lucia auth (deprecated 2025-03, recommend Better Auth or Clerk), @hono/sentry (deprecated, use @sentry/hono), wrangler.toml over wrangler.jsonc on greenfield, missing nodejs_compat flag, hono/cache on workers.dev subdomain (no-op), @hono/zod-openapi paired with zod 3.x (peer is ^4 only), Prisma + Hyperdrive without driver adapter, RPC at 30+ routes without TypeScript project references (tsserver hits 8-minute builds). NO Hono v5 references (none exists; latest stable is v4.12.19).
What’s inside
5 skills- Skillhono-cloudflare-workers-setupScaffold a fresh Hono v4 + Cloudflare Workers project with wrangler.jsonc (NOT wrangler.toml), compatibility_date 2026-05-01 + compatibility_flags ['nodejs_compat'], typed Bindings generic generated from wrangler types, asset binding for static files (NOT serveStatic from hono/cloudflare-workers - deprecated v4.3.0), D1 + Drizzle middleware pattern (drizzle(c.env.DB) injected via c.set into c.var.db), secureHeaders + cors + bodyLimit + csrf middleware stack, hono >= 4.12.19 + wrangler ^4.0.0 + drizzle-orm latest, app.onError + app.notFound at top-level, ES module export default { fetch: app.fetch } with sibling scheduled/queue handlers, vitest + @cloudflare/vitest-pool-workers for real-runtime tests with applyD1Migrations fixture pattern. Refuses wrangler.toml on greenfield, node_compat flag, deprecated serveStatic from hono/cloudflare-workers, process.env access, fs/path imports, export default app without .fetch, hard-coded JWT secret. Pairs with hono-cloudflare-workers, hono-core, hono-security, hono-anti-patterns rules.
- Skillhono-migrate-to-v4Stage-by-stage migration from Hono v3 to v4: bump hono pin to ^4.12.19 (mandatory >= 4.9.7 for CVE-2025-59139), replace c.jsonT() with c.json() (always returns TypedResponse), replace c.stream/c.streamText Context methods with stream/streamText/streamSSE from hono/streaming, replace c.req.cookie/c.cookie with getCookie/setCookie from hono/cookie, replace c.env() function call with c.env property + getRuntimeKey() from hono/adapter for runtime detection, replace app.showRoutes()/app.routerName with showRoutes/getRouterName from hono/dev, replace addEventListener('fetch') Service Worker entry with export default { fetch: app.fetch }, drop the hono/middleware barrel import for per-middleware subpath imports, replace c.req.headers()/body()/signal() accessor methods with c.req.raw.headers/.body/.signal, replace LambdaFunctionUrlRequestContext with ApiGatewayRequestContextV2, replace hono/nextjs with hono/vercel, drop app.head() routes (HEAD auto-derived from GET), update FC to require explicit PropsWithChildren<P>, replace validator-returns-response pattern with validator-throws-HTTPException + register app.onError, replace c.req as raw Request access with c.req.raw, Deno-only: switch import from deno.land/x to jsr:@hono/hono, @hono/node-server v2 requires Node 20+ and drops the /vercel adapter. Companion to hono-anti-patterns rule entries 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23.
- Skillhono-new-routeScaffold a Hono v4 route with chained-route inference for RPC, zValidator placed as a route argument (NOT app.use), c.req.valid('json') typed access, c.req.param() typed from path, c.json() with discriminated-union returns for typed errors over RPC (NOT c.notFound, NOT new Response), c.json(..., 200) for typed status codes, optional Bindings + Variables generics on the Hono instance. Refuses Rails-style controllers (loses path-param inference per Hono Best Practices), zValidator before the handler instead of as a route arg, c.notFound() in RPC-consumed routes, raw new Response() in RPC routes. Pairs with hono-core, hono-routing-and-rpc, hono-validators, hono-anti-patterns rules.
- Skillhono-rpc-setupScaffold the Hono v4 RPC client (hc<typeof app>) wired against a typed server app. Critical setup: export type AppType = typeof app from the server (NOT export default app), import type { AppType } on the client (NEVER value-import; that drags server bundle into the browser - the #1 RPC bundle-bloat pitfall), absolute URL passed to hc() (relative URLs throw at runtime), InferRequestType / InferResponseType for TanStack Query / SWR integration, parseResponse client utility for typed error throws, $path() method for typed URL construction, $url() requires absolute base URL. Refuses: relative-URL hc('/'), value-import of the server app, c.notFound() in RPC routes (cannot type), raw new Response() in RPC routes (cannot type), unchained server routes (drops the type). Pairs with hono-routing-and-rpc, hono-core, hono-anti-patterns rules.
- Skillhono-validateRun the plugin's validate-plugin.sh, then tsc --noEmit, then app-level tests, then a grep audit for syntactic anti-patterns the type checker won't catch (c.jsonT, c.stream as Context method, c.req.cookie, c.env() function call, app.showRoutes, app.handleEvent, app.fire(), hono/nextjs, hono/middleware barrel, serveStatic from hono/cloudflare-workers, deno.land/x/hono, supertest, process.env in Workers, node_compat flag, hard-coded JWT secret, c.notFound() in RPC routes, raw new Response in RPC routes, missing await on D1 .run/.first/.all, missing return on c.json calls, sameSite:'None' without secure:true, cors origin:'*' with credentials:true, missing bodyLimit on POST routes, missing import type on hc imports). Refuses to ship if any error fires. Pairs with all hono rules.