Home › Cloudflare Workers / Hono › Hono on Cloudflare Workers rules

Hono on Cloudflare Workers rules

Cursor rules for Hono 4 APIs on Cloudflare Workers with Wrangler, typed bindings, D1, KV, and Vitest.

CursorCloudflare Workers / Hono

How to use

Save this as .cursor/rules/hono-workers.mdc in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

---
description: Hono on Cloudflare Workers conventions
globs: ["src/**/*.ts","wrangler.jsonc","wrangler.toml"]
alwaysApply: false
---

# Hono on Cloudflare Workers

- Type the app with its bindings: `new Hono<{ Bindings: Env }>()`. Generate `Env` with `npx wrangler types` after changing `wrangler.jsonc`; don't hand-write binding types.
- Access bindings and secrets through `c.env`, never `process.env`. Secrets are set with `wrangler secret put`, never committed.
- Validate input with `@hono/zod-validator` (`zValidator('json', schema)`) and read it via `c.req.valid('json')`.
- Split routes into sub-apps (`app.route('/users', users)`) and export the app type for the `hc` RPC client when a frontend consumes it.
- D1: prepared statements with `.bind()`; schema changes as files in `migrations/` applied with `wrangler d1 migrations apply`.
- KV is eventually consistent; don't use it for counters or locks (use a Durable Object).
- Workers have CPU and memory limits: stream large responses, avoid Node-only packages unless `nodejs_compat` is on.
- Background work after the response goes in `c.executionCtx.waitUntil()`.
- Errors via `app.onError` returning JSON; throw `HTTPException` for expected failures.

## Don't
- Don't use global mutable state to share data across requests.

## Done when
`npx tsc --noEmit` and `npx vitest run` (with `@cloudflare/vitest-pool-workers`) pass and `npx wrangler deploy --dry-run` succeeds.