/infra-platform-cloudflare-workers

name: infra-platform-cloudflare-workers
description: Cloudflare Workers edge compute platform — Wrangler CLI, KV, D1, R2, Durable Objects, Queues, Workers AI

Cloudflare Workers Patterns

> **Quick Guide:** Cloudflare Workers run TypeScript/JavaScript on Cloudflare's global edge network with V8 isolates (not containers). Use `wrangler.jsonc` for configuration, `wrangler dev` for local development, and `wrangler deploy` for production. Access KV, D1, R2, Queues, Durable Objects, and Workers AI through type-safe bindings on the `env` parameter. Run `wrangler types` to auto-generate your `Env` interface. Stream large payloads — Workers have a 128 MB memory limit. Never store request-scoped state in module-level variables.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST run `wrangler types` to generate your Env interface — NEVER hand-write binding types)**

**(You MUST use `wrangler.jsonc` for new projects — Cloudflare recommends JSON config and some features are JSON-only)**

**(You MUST stream large request/response bodies — NEVER buffer entire payloads in memory (128 MB limit))**

**(You MUST avoid module-level mutable state — Workers reuse V8 isolates across requests, causing cross-request data leaks)**

**(You MUST use bindings for Cloudflare services (KV, D1, R2, Queues) — NEVER use REST APIs from within Workers)**

</critical_requirements>

---

Examples

• [Core Setup & Configuration](examples/core.md) — wrangler.jsonc, project init, fetch handler, secrets, multi-env, CI/CD, testing
• [KV Storage](examples/kv.md) — KV binding, typed get/put, TTL, stale-while-revalidate caching
• [D1 Database](examples/d1.md) — D1 binding, parameterized queries, batch ops, migrations, CRUD API
• [R2 Object Storage](examples/r2.md) — R2 binding, file upload/download/delete with streaming
• [Durable Objects](examples/durable-objects.md) — DO classes, SQLite, RPC, rate limiter, WebSocket chat
• [Routing & Middleware](examples/routing.md) — API framework integration, middleware, queues, cron, service bindings, AI, streaming
• [Quick Reference](reference.md) — Wrangler CLI commands, binding type signatures, config template, CPU limits

---

**Auto-detection:** Cloudflare Workers, wrangler, wrangler.toml, wrangler.jsonc, Workers KV, Cloudflare KV, D1 database, R2 bucket, Durable Objects, Cloudflare Queues, Workers AI, service binding, miniflare, compatibility_date, compatibility_flags, nodejs_compat, cloudflare:workers, ExportedHandler, DurableObject, wrangler dev, wrangler deploy, wrangler types, Cloudflare Pages Functions, edge worker, CF Worker

**When to use:**

• Deploying TypeScript/JavaScript to Cloudflare's edge network
• Configuring Wrangler CLI for local development and deployment
• Using Cloudflare bindings: KV, D1, R2, Queues, Durable Objects, Workers AI
• Building APIs on Workers with a framework (e.g., Hono)
• Implementing real-time features with Durable Objects and WebSockets
• Setting up cron triggers and scheduled handlers
• Configuring service bindings for worker-to-worker communication
• Managing environment variables, secrets, and multi-environment deploys

**When NOT to use:**

• Long-running compute tasks exceeding CPU time limits (use traditional servers or Workflows)
• Applications requiring persistent TCP connections to external databases without Hyperdrive
• Workloads needing more than 128 MB memory per request

**Key patterns covered:**

• Wrangler configuration (`wrangler.jsonc`) and project setup
• Fetch handler, scheduled handler, and queue handler
• KV key-value storage (caching, config, session data)
• D1 SQLite database (relational data at the edge)
• R2 S3-compatible object storage (files, uploads, assets)
• Durable Objects (stateful edge compute, WebSockets, coordination)
• Cloudflare Queues (async message processing)
• Workers AI (inference at the edge)
• Framework integration (Hono examples) with typed bindings
• Environment variables, secrets, and multi-environment config
• Service bindings (worker-to-worker RPC)
• Cron triggers and scheduled workers
• Streaming and performance optimization
• Testing with Workers-native test pool

---

<philosophy>

Philosophy

Cloudflare Workers run on V8 isolates (not containers) across 300+ data centers worldwide. They start in under 5ms with zero cold starts. The programming model is fundamentally different from traditional servers:

1. **Bindings over APIs** - Access Cloudflare services (KV, D1, R2, Queues) through direct in-process bindings on the `env` parameter, not REST API calls. Bindings have zero network hop and zero auth overhead. 2. **Stateless by default** - Each request gets a fresh execution context. Workers reuse V8 isolates, so module-level variables persist across requests — this is a bug source, not a feature. 3. **Stream everything** - Workers have a 128 MB memory limit. Buffer nothing; stream request and response bodies using `TransformStream` and `pipeTo`. 4. **Edge-first architecture** - Code runs closest to the user. Use Durable Objects when you need coordination or state; use D1/KV/R2 for persistence.

**When to use Workers:**

• API endpoints, middleware, and request routing
• Caching layers and content transformation
• Webhook receivers and event processors
• Real-time collaboration (with Durable Objects)
• Full-stack applications (with Workers Static Assets or Pages)

**When NOT to use Workers:**

• CPU-intensive compute exceeding limits (10ms free / 30s paid per request)
• Workloads requiring more than 128 MB memory
• Applications needing persistent database connections (use Hyperdrive as a proxy)
• Long-running background jobs exceeding limits (use Workflows for durable execution)

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Project Setup and Wrangler Configuration

Every Workers project starts with `wrangler.jsonc`. Cloudflare recommends JSON format — some newer features are JSON-only. Run `wrangler types` after changing bindings to re