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

(You MUST use

wrangler.jsonc

(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 — wrangler.jsonc, project init, fetch handler, secrets, multi-env, CI/CD, testing
• KV Storage — KV binding, typed get/put, TTL, stale-while-revalidate caching
• D1 Database — D1 binding, parameterized queries, batch ops, migrations, CRUD API
• R2 Object Storage — R2 binding, file upload/download/delete with streaming
• Durable Objects — DO classes, SQLite, RPC, rate limiter, WebSocket chat
• Routing & Middleware — API framework integration, middleware, queues, cron, service bindings, AI, streaming
• Quick Reference — 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

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)

Core Patterns

Pattern 1: Project Setup and Wrangler Configuration

Every Workers project starts with

wrangler.jsonc

wrangler types

Env

// 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 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>

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 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")

expirationTtl

ctx.waitUntil()

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 for stale-while-revalidate pattern and full caching examples.

Pattern 4: D1 SQLite Database

D1 is serverless SQLite at the edge. Always use parameterized queries via

prepare().bind()

batch()

withSession()

const user = await db
  .prepare("SELECT * FROM users WHERE email = ?")
  .bind(email)
  .first<User>();

const { results } = await db
  .prepare("SELECT * FROM users LIMIT ? OFFSET ?")
  .bind(DEFAULT_PAGE_SIZE, offset)
  .all<User>();

See examples/d1.md for migrations, batch operations, and full CRUD API.

Pattern 5: R2 Object Storage

R2 is S3-compatible storage with zero egress fees. Always stream R2 bodies directly to responses — never call

.arrayBuffer()

.text()

const object = await env.BUCKET.get(key);
if (!object) return new Response("Not Found", { status: 404 });
const headers = new Headers();
object.writeHttpMetadata(headers);
return new Response(object.body, { headers }); // Stream directly

See examples/r2.md for file service with content-type validation and list operations.

Pattern 6: Durable Objects (Stateful Edge Compute)

Durable Objects provide single-threaded, strongly consistent compute. Each instance has SQLite storage. Use RPC methods (not fetch) and

blockConcurrencyWhile

import { DurableObject } from "cloudflare:workers";

export class Counter extends DurableObject<Env> {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    ctx.blockConcurrencyWhile(async () => {
      this.ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS ...");
    });
  }
  async increment(name: string): Promise<number> {
    /* RPC method */
  }
}

When to use: Coordination (chat, collaboration), per-entity state (sessions, game instances), WebSocket connections, rate limiting.

When not to use: Stateless requests, high fan-out, global rate limiting (bottleneck).

See examples/durable-objects.md for rate limiter and WebSocket chat with hibernation.

Pattern 7: Queues, Cron, Service Bindings, Workers AI

Queues decouple producers from consumers with at-least-once delivery and configurable retries. Cron triggers invoke Workers on a schedule. Service bindings enable zero-cost worker-to-worker calls. Workers AI runs inference on Cloudflare's GPU network.

See examples/routing.md for all these patterns with full configuration and code examples.

Pattern 8: API Framework Integration

For structured APIs, use a framework with typed bindings (Hono is the Workers ecosystem standard). Export the framework's

fetch

import { Hono } from "hono";
const app = new Hono<{ Bindings: Env }>();

app.get("/users/:id", async (c) => {
  const user = await c.env.DB.prepare("SELECT * FROM users WHERE id = ?")
    .bind(c.req.param("id"))
    .first();
  return user ? c.json(user) : c.json({ error: "Not found" }, 404);
});

export default app;

See examples/routing.md for production API with middleware, error handling, and multi-handler setup.

Performance Optimization

Request Processing

"mode": "smart"

ctx.waitUntil()

nodejs_compat

Storage Performance

Hyperdrive for External Databases

When connecting to PostgreSQL/MySQL outside Cloudflare, always use Hyperdrive. It maintains a connection pool close to your database, eliminating per-request TCP/TLS overhead.

CPU Time Limits

<decision_framework>

Decision Framework

Choosing a Storage Primitive

What kind of data?
  |
  +-- Key-value pairs (cache, config, sessions)
  |     +-- Read-heavy, eventual consistency OK --> KV
  |     +-- Strong consistency needed --> Durable Objects
  |
  +-- Relational data with queries
  |     +-- Edge-native SQLite --> D1
  |     +-- External PostgreSQL/MySQL --> Hyperdrive
  |
  +-- Files and blobs (images, documents)
  |     +-- S3-compatible storage --> R2
  |
  +-- Coordination state (chat, multiplayer, collaboration)
  |     +-- Single-threaded consistency --> Durable Objects
  |
  +-- Message passing / background work
        +-- Simple fan-out, buffering --> Queues
        +-- Multi-step durable execution --> Workflows

Choosing Between Workers and Pages

What are you building?
  |
  +-- API only (no frontend) --> Workers
  |
  +-- Static site + API --> Pages with Functions
  |
  +-- Full-stack with SSR --> Pages (framework) or Workers + Static Assets
  |
  +-- Background processing / cron --> Workers (Pages lacks cron support)
  |
  +-- Real-time / WebSockets --> Workers + Durable Objects

When to Use Durable Objects vs D1

Do you need coordination between concurrent requests?
  |
  +-- YES (chat, game, collaboration) --> Durable Objects
  |     +-- Single-threaded, no race conditions
  |     +-- WebSocket support with hibernation
  |     +-- Per-entity sharding (one DO per room/session)
  |
  +-- NO (CRUD, reporting, querying) --> D1
        +-- Full SQL support
        +-- Cross-entity queries
        +-- Traditional database patterns

</decision_framework>

Integration Guide

Cloudflare Platform Services:

• Hyperdrive: Connection pooling proxy for external PostgreSQL/MySQL — eliminates per-request TCP/TLS overhead
• Vectorize: Vector database for embeddings and semantic search with Workers AI
• Cloudflare Pages: Static site hosting with Workers-powered functions for full-stack apps
• GitHub Actions:

  cloudflare/wrangler-action@v3

  for CI/CD deployment

Framework & ORM Compatibility:

Workers are compatible with edge-optimized frameworks and ORMs that support the V8 runtime. Use

Hono<{ Bindings: Env }>

Testing:

Use

@cloudflare/vitest-pool-workers

Comparable Platforms:

• AWS Lambda@Edge / CloudFront Functions
• Vercel Edge Functions
• Deno Deploy

<red_flags>

RED FLAGS

High Priority Issues:

• Storing request-scoped data in module-level variables (V8 isolate reuse causes cross-request leaks)
• Buffering entire request/response bodies with

  .text()

  /

  .arrayBuffer()

  (128 MB memory limit)
• Hand-writing

  Env

  interface instead of running

  wrangler types

  (mismatches between config and code)
• Using REST APIs for KV/D1/R2/Queues from within Workers instead of bindings (unnecessary latency and auth overhead)
• Putting secrets in

  wrangler.jsonc

  , source code, or environment variables (use

  wrangler secret put

  )
• Creating a single global Durable Object for all traffic (bottleneck at ~1000 req/sec)

Medium Priority Issues:

• Using

  wrangler.toml

  for new projects (JSON format recommended, some features JSON-only)
• Outdated

  compatibility_date

  (misses runtime improvements and bug fixes)
• Missing

  observability

  config (production Workers are a black box without logs/traces)
• Destructuring

  ctx

  in fetch handler (loses

  this

  binding,

  ctx.waitUntil

  throws "Illegal invocation")
• Using

  exec()

  for D1 queries instead of

  prepare().bind()

  (no parameterization, SQL injection risk)
• Not reciprocating WebSocket close in Durable Objects (causes 1006 errors)

Common Mistakes:

• Forgetting that KV is eventually consistent (~60s propagation) and expecting instant reads after writes
• Using

  Math.random()

  for security-sensitive tokens (use

  crypto.randomUUID()

  or

  crypto.getRandomValues()

  )
• Not using

  ctx.waitUntil()

  for post-response background work (work may be cancelled when response is sent)
• Comparing secrets with

  ===

  instead of

  crypto.subtle.timingSafeEqual()

  (timing side-channel attack)
• Using

  passThroughOnException()

  as error handling (hides bugs, use explicit try/catch)
• Floating promises (not awaited, not returned, not passed to

  waitUntil()

  ) causing silent failures — enable

  @typescript-eslint/no-floating-promises

  to catch at dev time

Gotchas and Edge Cases:

• Bindings (KV, D1, R2, etc.) are NOT inherited across Wrangler environments — you must re-declare them per environment

• wrangler dev

  uses local simulation by default; use

  --remote

  to test against real Cloudflare services
• D1 batch operations execute sequentially (not in parallel) but atomically
• Durable Objects in-memory state is lost on eviction — always persist important data to SQLite first
• Unnecessary

  await

  between DO storage writes breaks write coalescing — batch writes happen atomically when you don't await between them
• DO alarm handlers may fire multiple times — design them to be idempotent
• Using

  blockConcurrencyWhile()

  on every request limits throughput to ~200 req/sec — use it only for initialization
• Workers on the free plan have a 10ms CPU time limit per request (not wall-clock time — I/O waiting is free)
• Cron trigger changes take up to 15 minutes to propagate globally

• .dev.vars

  file is for local secrets only and must be gitignored
• The

  env

  parameter from

  cloudflare:workers

  import creates a fresh reference; avoid caching binding derivatives at module scope

</red_flags>

<critical_reminders>

CRITICAL REMINDERS

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

import type

, named constants)

(You MUST run

wrangler types

(You MUST use

wrangler.jsonc

(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)

Failure to follow these rules will result in memory crashes (buffering), data leaks (module state), type mismatches (hand-written Env), unnecessary latency (REST over bindings), and secret exposure (secrets in config).

</critical_reminders>