workers-dev-experience

# Cloudflare Workers Developer Experience

Local development setup with Wrangler, Miniflare, and modern tooling.

## Quick Start

```bash
# Create new project
bunx create-cloudflare@latest my-worker

# Or from scratch
mkdir my-worker && cd my-worker
bun init -y
bun add -d wrangler @cloudflare/workers-types

# Start local development
bunx wrangler dev
```

## Essential wrangler.jsonc

```jsonc
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2024-12-01",

  // Development settings
  "dev": {
    "port": 8787,
    "local_protocol": "http"
  },

  // Environment variables (non-secret)
  "vars": {
    "ENVIRONMENT": "development"
  },

  // Bindings
  "kv_namespaces": [
    { "binding": "KV", "id": "abc123", "preview_id": "def456" }
  ],

  "d1_databases": [
    { "binding": "DB", "database_id": "xyz789", "database_name": "my-db" }
  ],

  "r2_buckets": [
    { "binding": "BUCKET", "bucket_name": "my-bucket" }
  ]
}
```

## Critical Rules

1. **Always use `wrangler dev` for local testing** - Simulates Cloudflare runtime accurately
2. **Set `compatibility_date`** - Controls runtime behavior, update quarterly
3. **Use preview IDs for local dev** - Separate from production bindings
4. **Configure TypeScript properly** - Use `@cloudflare/workers-types`
5. **Enable source maps** - Better error stacks in development

## Top 6 Errors Prevented

| Error | Symptom | Prevention |
|-------|---------|------------|
| Module not found | Import errors on deploy | Set `"moduleResolution": "bundler"` in tsconfig |
| Binding undefined | `env.KV is undefined` locally | Add `preview_id` to KV namespace config |
| HMR not working | Changes not reflecting | Check port conflicts, use `--local` flag |
| D1 schema mismatch | Queries fail locally | Run migrations on local DB |
| Type errors | Missing binding types | Generate types with `wrangler types` |
| CORS issues | Browser blocking requests | Add CORS header