dotfiles/dot_agents/skills/cloudflare/references/workers

Cloudflare Workers

Expert guidance for building, deploying, and optimizing Cloudflare Workers applications.

Overview

Cloudflare Workers run on V8 isolates (NOT containers/VMs):

• Extremely fast cold starts (< 1ms)
• Global deployment across 300+ locations
• Web standards compliant (fetch, URL, Headers, Request, Response)
• Support JS/TS, Python, Rust, and WebAssembly

Key principle: Workers use web platform APIs wherever possible for portability.

Module Worker Pattern (Recommended)

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    return new Response('Hello World!');
  },
};

Handler parameters:

• request: Incoming HTTP request (standard Request object)
• env: Environment bindings (KV, D1, R2, secrets, vars)
• ctx: Execution context (waitUntil, passThroughOnException)

Essential Commands

npx wrangler dev                    # Local dev
npx wrangler dev --remote           # Remote dev (actual resources)
npx wrangler deploy                 # Production
npx wrangler deploy --env staging   # Specific environment
npx wrangler tail                   # Stream logs
npx wrangler secret put API_KEY     # Set secret

When to Use Workers

• API endpoints at the edge
• Request/response transformation
• Authentication/authorization layers
• Static asset optimization
• A/B testing and feature flags
• Rate limiting and security
• Proxy/routing logic
• WebSocket applications

Quick Start

npm create cloudflare@latest my-worker -- --type hello-world
cd my-worker
npx wrangler dev

Handler Signatures

// HTTP requests
async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response>

// Cron triggers
async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext): Promise<void>

// Queue consumer
async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext): Promise<void>

// Tail consumer
async tail(events: TraceItem[], env: Env, ctx: ExecutionContext): Promise<void>

Resources

Docs: https://developers.cloudflare.com/workers/
Examples: https://developers.cloudflare.com/workers/examples/
Runtime APIs: https://developers.cloudflare.com/workers/runtime-apis/

In This Reference

• Configuration - wrangler.jsonc setup, bindings, environments
• API - Runtime APIs, bindings, execution context
• Patterns - Common workflows, testing, optimization
• Frameworks - Hono, routing, validation
• Gotchas - Common issues, limits, troubleshooting

Reading Order

Task	Start With	Then Read
First Worker	README → Configuration → API	Patterns
Add framework	Frameworks	Configuration (bindings)
Add storage/bindings	Configuration → API (binding usage)	See Also links
Debug issues	Gotchas	API (specific binding docs)
Production optimization	Patterns	API (caching, streaming)
Type safety	Configuration (TypeScript)	Frameworks (Hono typing)

See Also

• KV - Key-value storage
• D1 - SQL database
• R2 - Object storage
• Durable Objects - Stateful coordination
• Queues - Message queues
• Wrangler - CLI tool reference