Cloudflare Workers Development Skill

A Claude Code skill for building and deploying applications on the Cloudflare Workers platform, covering Workers, Pages, KV, D1, R2, Durable Objects, and the full Cloudflare edge computing ecosystem.

When to Use This Skill

Choose this skill when:

• Building serverless APIs or edge functions on Cloudflare Workers
• Deploying full-stack applications with Cloudflare Pages
• Implementing edge caching, rate limiting, or request routing
• Working with Cloudflare storage (KV, D1, R2, Durable Objects)
• Migrating existing applications to edge computing
• Setting up CI/CD pipelines with Wrangler

Consider alternatives when:

• You need long-running background jobs over 30 seconds (use a traditional server or queue)
• You need GPU compute for ML inference (use a cloud GPU provider)
• You need a relational database with complex joins (D1 has SQLite limitations)

Quick Start

Copy
# Install Wrangler CLI
npm install -g wrangler

# Create a new Workers project
wrangler init my-worker
cd my-worker

# Develop locally with hot reload
wrangler dev

# Deploy to Cloudflare
wrangler deploy

Copy
// src/index.ts - Basic Worker
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === '/api/hello') {
      return Response.json({ message: 'Hello from the edge!' });
    }

    if (url.pathname === '/api/data') {
      // Read from KV
      const value = await env.MY_KV.get('key');
      return Response.json({ value });
    }

    return new Response('Not Found', { status: 404 });
  }
} satisfies ExportedHandler<Env>;

Copy
# wrangler.toml
name = "my-worker"
main = "src/index.ts"
compatibility_date = "2026-03-01"

[[kv_namespaces]]
binding = "MY_KV"
id = "abc123"

[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "def456"

[[r2_buckets]]
binding = "BUCKET"
bucket_name = "my-bucket"

Core Concepts

Cloudflare Services

Service	Type	Best For	Limits
Workers	Compute	API endpoints, routing, middleware	10ms-30s CPU time
Pages	Hosting	Full-stack apps, static sites	Auto-deployed from Git
KV	Key-Value Store	Configuration, cached data, sessions	Eventually consistent
D1	SQL Database	Structured data, relational queries	SQLite-based
R2	Object Storage	Files, images, backups	S3-compatible API
Durable Objects	Stateful Workers	WebSockets, counters, coordination	Single-instance consistency
Queues	Message Queue	Background processing, event-driven	At-least-once delivery

Durable Objects for Stateful Logic

Copy
export class ChatRoom implements DurableObject {
  private connections: Set<WebSocket> = new Set();

  constructor(private state: DurableObjectState, private env: Env) {}

  async fetch(request: Request): Promise<Response> {
    const pair = new WebSocketPair();
    const [client, server] = Object.values(pair);

    this.state.acceptWebSocket(server);
    this.connections.add(server);

    server.addEventListener('message', (event) => {
      for (const conn of this.connections) {
        if (conn !== server) conn.send(event.data);
      }
    });

    return new Response(null, { status: 101, webSocket: client });
  }
}

Configuration

Parameter	Type	Default	Description
name	string	—	Worker name used in deployment URL
main	string	"src/index.ts"	Entry point file for the worker
compatibility_date	string	—	Cloudflare runtime compatibility date
routes	array	[]	Custom domain routes for the worker
cron_triggers	array	[]	Scheduled CRON triggers
vars	object	{}	Environment variables (non-secret)
node_compat	boolean	false	Enable Node.js API compatibility mode
workers_dev	boolean	true	Enable workers.dev subdomain

Best Practices

1. Use bindings instead of fetch calls for Cloudflare services — access KV, D1, R2, and Durable Objects through env bindings rather than HTTP requests; bindings are faster and don't count against your subrequest limits.

2. Keep Workers stateless and push state to storage — Workers can be evicted at any time; store all important state in KV, D1, or Durable Objects rather than in-memory variables.

3. Use waitUntil() for non-blocking work — fire-and-forget tasks like logging, analytics, or cache warming should use context.waitUntil(promise) so they don't block the response to the user.

4. Set appropriate cache headers for edge caching — Cloudflare's CDN respects cache headers; use Cache-Control with appropriate max-age and s-maxage values to reduce Worker invocations for cacheable responses.

5. Test locally with wrangler dev before deploying — Wrangler's local development mode simulates the Workers runtime including bindings, so catch issues before they reach production.

Common Issues

KV reads return stale data — KV is eventually consistent with a propagation delay of up to 60 seconds. If you need immediate consistency after writes, read from the same region or use Durable Objects for strongly consistent state.

Worker exceeds CPU time limit — Free tier Workers have a 10ms CPU time limit (paid tier: 30s). Optimize by reducing computation, using streaming responses, or breaking work into multiple Worker invocations connected by Queues.

D1 queries fail with "too many SQL variables" — D1 limits bound parameters per query. For large batch inserts, split them into chunks of 100 rows per INSERT statement and execute multiple queries within a transaction.