CLAUDE.md for Cloudflare Workers

A CLAUDE.md for edge development: stateless handler design, binding regeneration workflow, and wrangler tail debugging.

# CLAUDE.md - edge-api (Cloudflare Workers)

## Commands
```bash
pnpm dev                                  # wrangler dev on :8787
pnpm vitest run                           # tests inside workerd
pnpm exec wrangler deploy --dry-run       # bundle check without deploying
pnpm exec wrangler types                  # regen binding types after wrangler.jsonc edits
pnpm exec wrangler tail                   # live production logs
```

## Architecture
- Hono app; routes in `src/routes/`, one file per resource, registered in
  `src/index.ts`. Env bindings (D1 `DB`, KV `CACHE`) are typed from
  `worker-configuration.d.ts`.
- This runs on workerd, not Node. No filesystem, no Node globals, isolates
  recycle whenever - design every handler stateless.

## Conventions
- Zod-validate all input at the route edge; D1 via prepared statements in
  `src/lib/db.ts` only.
- KV writes set `expirationTtl` explicitly.
- New routes follow `src/routes/items.ts` for validation, error shape, and
  pagination.

## Workflow
- After editing `wrangler.jsonc`: regenerate types, then fix what breaks.
- Debug production with `wrangler tail`, not by adding console noise and
  redeploying repeatedly.
- Migrations: test with `--local` first, then apply to remote.

## Do not
- Do not import Node built-ins; check the runtime compat table before adding
  any dependency.
- Do not store per-user data in module scope - isolates are shared.
- Do not put secrets in `vars`; use `wrangler secret put`.

These examples are released under CC0. Use them freely, no attribution required. They are provided as is, without warranty of any kind: review and adapt them to your project before use, as you are responsible for the outcome of applying them.