cloudflare-workers

• Runtime & handlers → references/runtime.md
• Bindings overview → references/bindings.md
• Wrangler configuration → references/wrangler.md
• Local development → references/local-dev.md
• Static assets → references/assets.md
• Testing → references/testing.md

• Building serverless APIs or full-stack applications
• Running edge functions with global distribution
• Connecting to Cloudflare storage (KV, R2, D1, Durable Objects)
• Running AI inference with Workers AI
• Configuring Wrangler CLI and wrangler.toml
• Setting up local development with Miniflare
• Testing Workers with Vitest

```typescript

export default {

async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise {

return new Response("Hello, World!");

},

} satisfies ExportedHandler;

```

| Handler | Trigger | Use Case |

| ----------- | -------------- | ---------------- |

| fetch | HTTP request | APIs, websites |

| scheduled | Cron trigger | Background jobs |

| queue | Queue message | Async processing |

| email | Email received | Email routing |

Access Cloudflare resources via env object.

| Binding | Type | Local Dev |

| ----------------- | ------------------------ | -------------- |

| KV | KVNamespace | ✅ Simulated |

| R2 | R2Bucket | ✅ Simulated |

| D1 | D1Database | ✅ Simulated |

| Durable Objects | DurableObjectNamespace | ✅ Simulated |

| Queues | Queue | ✅ Simulated |

| Workers AI | Ai | ❌ Remote only |

| Vectorize | VectorizeIndex | ❌ Remote only |

| Browser Rendering | Fetcher | ❌ Remote only |

| Hyperdrive | Hyperdrive | ❌ Remote only |

| Static Assets | Fetcher | ✅ Simulated |

| Service Binding | Fetcher | ✅ Simulated |

```jsonc

// wrangler.jsonc

{

"$schema": "./node_modules/wrangler/config-schema.json",

"name": "my-worker",

"main": "src/index.ts",

"compatibility_date": "2025-03-07",

"compatibility_flags": ["nodejs_compat"],

"observability": {

"enabled": true,

"head_sampling_rate": 1

}

}

```

```bash

# Development

npx wrangler dev # Local dev (Miniflare)

npx wrangler dev --remote # Remote dev (code on Cloudflare)

# Deployment

npx wrangler deploy # Deploy to production

npx wrangler versions upload # Upload without deploying

npx wrangler versions deploy # Promote version

# Secrets

npx wrangler secret put KEY # Add secret

npx wrangler secret list # List secrets

# Types

npx wrangler types # Generate TypeScript types

```

```toml

# wrangler.toml

compatibility_date = "2025-03-07"

compatibility_flags = ["nodejs_compat"]

```

Key flags:

• nodejs_compat — Enable Node.js APIs
• nodejs_compat_v2 — Improved process implementation

Fetch Handler with Routing

```typescript

export default {

async fetch(request: Request, env: Env): Promise {

const url = new URL(request.url);

if (url.pathname === "/api/hello") {

return Response.json({ message: "Hello!" });

}

if (url.pathname.startsWith("/static/")) {

return env.ASSETS.fetch(request);

}

return new Response("Not Found", { status: 404 });

},

};

```

Scheduled Handler (Cron)

```typescript

export default {

async scheduled(controller: ScheduledController, env: Env, ctx: ExecutionContext) {

ctx.waitUntil(doBackgroundWork(env));

},

};

```

```toml

# wrangler.toml

[triggers]

crons = ["0 "] # Every hour

```

Queue Consumer

```typescript

export default {

async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext) {

for (const message of batch.messages) {

console.log(message.body);

message.ack();

}

},

};

```

• Do NOT store secrets in wrangler.toml — use wrangler secret put
• Do NOT use remote: true for Durable Objects or Workflows — unsupported
• Do NOT expect Workers AI to work locally — always requires remote connection
• Do NOT omit compatibility_date — defaults to oldest date (2021-11-02)
• Do NOT use Service Worker syntax for new projects — use ES Modules
• Do NOT mix Service Worker and Module syntax in same project

| Issue | Solution |

| ---------------------- | ------------------------------------------------------------- |

| Local bindings empty | Add --local flag to Wrangler KV/R2/D1 commands |

| AI not working locally | Use remote: true in ai binding config |

| Node APIs unavailable | Add nodejs_compat to compatibility_flags |

| First deploy fails | Use wrangler deploy, not versions upload for first deploy |

• cloudflare-pages — Full-stack hosting with Git deployment
• cloudflare-d1 — D1 database operations
• cloudflare-r2 — R2 object storage
• cloudflare-kv — KV namespace operations
• cloudflare-durable-objects — Stateful coordination