[Worker Name]

An edge API on Cloudflare Workers. Hono in front, D1 for state, KV for sessions.

Source of truth

Wrangler-driven. wrangler deploy from local pushes the worker. The deployed version is canonical. Preview deployments via wrangler versions deploy per branch.

Tech stack

TypeScript on Cloudflare Workers runtime (V8 isolates, not Node). Hono 4 for routing (small, fast, edge-native). D1 for SQL at the edge (SQLite-compatible). KV for sessions + cache. R2 for object storage. Durable Objects only when you need strict consistency (chat rooms, counters, locks). Wrangler for dev + deploy.

Deploy

wrangler deploy for production. wrangler versions deploy for previews. Routes assigned via wrangler.toml (yourdomain.com/api/*).

File map

• src/index.ts Hono app, route mounting, env typing
• src/routes/ route modules
• src/middleware/ auth, CORS, request ID
• src/db/ D1 query helpers + migrations (migrations/0001_init.sql etc)
• src/durable-objects/ DO classes (if used)
• wrangler.toml bindings (D1, KV, R2, DOs), routes, env
• worker-configuration.d.ts auto-generated Env types

.env / wrangler bindings

• D1_DB Cloudflare D1 database binding
• SESSIONS KV namespace binding for sessions
• R2_BUCKET (if needed)
• JWT_SECRET set via wrangler secret put JWT_SECRET
• STRIPE_SECRET if relevant, also via wrangler secret put

Hard rules

• Runtime is V8 isolate, NOT Node. fs, crypto Node module, raw Buffer do not exist. Use Web APIs.
• D1 queries via prepared statements only (.prepare().bind(...).all()). String concat is SQL injection.
• KV reads are eventually consistent globally. Don't use KV for anything that needs read-your-writes.
• Secrets via wrangler secret put. Never in wrangler.toml (committed file).
• CPU limit on Workers: 50ms paid, 10ms free tier. Heavy work goes to a separate Worker or Queue.
• Migrations applied with wrangler d1 migrations apply DB_NAME.

Recent significant changes

• 2026-05-04: Scaffolded. Locked: Hono over itty-router (more batteries), D1 over Postgres-via-fetch (latency), KV for sessions (sub-ms reads at the edge).

Next session: start here

1. npm create cloudflare@latest if starting fresh, or clone this CLAUDE.md into existing project.
2. wrangler d1 create your-db. Update wrangler.toml with returned ID.
3. wrangler d1 migrations create your-db init. Write schema.
4. wrangler dev to test locally.
5. wrangler deploy once you have a route to deploy.