infra-platform-cloudflare-workers

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

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(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 regenerate the Env interface.

// wrangler.jsonc
{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-api",
  "main": "src/index.ts",
  "compatibility_date": "2025-09-15",
  "compatibility_flags": ["nodejs_compat"],
  "observability": { "enabled": true },
  "placement": { "mode": "smart" },
  "upload_source_maps": true,
}

See [examples/core.md](examples/core.md) for full project initialization, multi-environment config, secrets management, CI/CD, and testing setup.

Pattern 2: Fetch Handler (Request/Response)

The fetch handler is the entry point for HTTP requests. Use satisfies ExportedHandler<Env> for type safety.

import type { ExportedHandler } from "cloudflare:workers";

export default {
  async fetch(request, env, ctx): Promise<Response> {
    const url = new URL(request.url);
    if (url.pathname === "/health") {
      return Response.json({ status: "healthy" });
    }
    return new Response("Not Found", { status: 404 });
  },
} satisfies ExportedHandler<Env>;

Never store mutable state in module-level variables — V8 isolate reuse causes cross-request data leaks. See [examples/core.md](examples/core.md) for complete handler with CORS and routing.

Pattern 3: KV Key-Value Storage

KV is an eventually-consistent key-value store for read-heavy workloads. Use typed get<T>(key, "json"), always set expirationTtl, and use ctx.waitUntil() for non-blocking writes.

const CACHE_TTL_SECONDS = 3_600;
const profile = await env.CACHE.get<UserProfile>(`user:${id}`, "json");
ctx.waitUntil(
  env.CACHE.put(`user:${id}`, JSON.stringify(data), {
    expirationTtl: CACHE_TTL_SECONDS,
  }),
);

When to use: Read-heavy workloads (config, cache, feature flags) where eventual consistency is acceptable (~60s propagation).

When not to use: Relational data (use D1), frequent writes to same key, strong consistency (use Durable Objects).

See [examples/kv.md](examples/kv.md) for stale-while-revalidate pattern