Skip to main content
skill CX Codex

cloudflare-worker-dev — Claude Code skill: setup

The cloudflare-worker-dev skill guides Cloudflare Workers work for edge APIs, KV caching, request limits, and real-time coordination.

MIT 189 installs ★ 274 updated 2026-10-30

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add curiositech/some_claude_skills --skill cloudflare-worker-dev -a claude-code
Open on GitHub

What cloudflare-worker-dev does

The skill covers Cloudflare Workers with KV and Durable Objects. It helps an agent shape serverless APIs, pick storage patterns for cached data and configuration, add request limits, and coordinate state at the edge. The material also outlines R2, D1, and scheduled handlers.

Examples use src/index.ts and wrangler.toml, with CORS handling, JSON responses, KV operations, geohash-based cache keys, debug headers, and IP-based limits. TypeScript and wrangler are part of the shown setup. The instructions use Read, Write, Edit, Bash, Grep, and Glob tools.

This skill does not cover Cloudflare Pages configuration, DNS management, or general CDN settings.

What it helps with

  • build an API on Cloudflare Workers
  • configure caching with KV
  • add IP-based request limits
  • coordinate real-time state
  • define CORS and cron handlers

Example prompts for the agent

  • Build a serverless API on Cloudflare Workers with a /health route and CORS handling.
  • Set up KV caching in src/index.ts and add the bindings to wrangler.toml.
  • Add IP-based request limiting with KV storage.

How to install cloudflare-worker-dev

1Skills CLI (Vercel)

npx skills add curiositech/some_claude_skills --skill cloudflare-worker-dev -a claude-code

2Manually: put the files in place

~/.claude/skills/cloudflare-worker-dev/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/cloudflare-worker-dev/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about cloudflare-worker-dev

How do I install cloudflare-worker-dev in Claude Code?

Run npx skills add curiositech/some_claude_skills --skill cloudflare-worker-dev -a claude-code, then check ~/.claude/skills/cloudflare-worker-dev/SKILL.md.

What does cloudflare-worker-dev do?

It guides Workers development for APIs, caching, rate limiting, and real-time features. Its examples cover KV, Durable Objects, and wrangler.toml configuration.

Which platforms support cloudflare-worker-dev?

The skill supports Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode.

Source text

SKILL.md · MIT
---
name: cloudflare-worker-dev
description: Cloudflare Workers, KV, Durable Objects, and edge computing development. Use for serverless APIs, caching, rate limiting, real-time features. Activate on "Workers", "KV", "Durable Objects",
  "wrangler", "edge function", "Cloudflare". NOT for Cloudflare Pages configuration (use deployment docs), DNS management, or general CDN settings.
allowed-tools: Read,Write,Edit,Bash,Grep,Glob
metadata:
  category: DevOps & Site Reliability
  tags:
  - cloudflare
  - workers
  - edge-computing
  - serverless
  - kv
  - caching
  - rate-limiting
  pairs-with:
  - skill: devops-automator
    reason: CI/CD pipelines deploy and manage Cloudflare Worker deployments across environments
  - skill: caching-strategies
    reason: Workers KV and Cache API are key components of edge caching architectures
  - skill: modern-auth-2026
    reason: Workers often handle auth token validation and session management at the edge
  - skill: api-architect
    reason: Workers frequently serve as API gateways requiring proper REST/GraphQL design
---

# Cloudflare Workers Development

Build high-performance edge APIs with Workers, KV for caching, and Durable Objects for real-time coordination.

## Core Architecture

### When to Use What

| Service | Use Case | Characteristics |
|---------|----------|-----------------|
| **Workers** | Request handling, API logic | Stateless, 50ms CPU (free), 30s (paid) |
| **KV** | Caching, config, sessions | Eventually consistent, fast reads |
| **Durable Objects** | Real-time, coordination | Strongly consistent, single-threaded |
| **R2** | File storage | S3-compatible, no egress fees |
| **D1** | SQLite at edge | Serverless SQL, good for reads |

## Worker Fundamentals

### Basic Worker Structure

```typescript
// src/index.ts
export interface Env {
  MEETING_CACHE: KVNamespace;
  RATE_LIMIT: KVNamespace;
  API_KEY: string;
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const url = new URL(request.url);

    // CORS handling
    if (request.method === 'OPTIONS') {
      return handleCORS();
    }

    try {
      // Route handling
      if (url.pathname === '/health') {
        return json({ status: 'ok' });
      }

      if (url.pathname.startsWith('/api/')) {
        return handleAPI(request, env, ctx);
      }

      return new Response('Not Found', { status: 404 });
    } catch (error) {
      console.error('Worker error:', error);
      return json({ error: 'Internal error' }, 500);
    }
  },

  // Cron trigger
  async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext) {
    ctx.waitUntil(runScheduledTask(env));
  }
};
```

### CORS Headers (Essential)

```typescript
const CORS_HEADERS = {
  'Access-Control-Allow-Origin': '*', // Or specific origin
  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
  'Access-Control-Max-Age': '86400',
};

function handleCORS(): Response {
  return new Response(null, { status: 204, headers: CORS_HEADERS });
}

function json(data: unknown, status = 200): Response {
  return new Response(JSON.stringify(data), {
    status,
    headers: {
      ...CORS_HEADERS,
      'Content-Type': 'application/json',
    },
  });
}
```

### wrangler.toml Configuration

```toml
name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-01-01"

# KV Namespaces
[[kv_namespaces]]
binding = "MEETING_CACHE"
id = "abc123..."  # Production
preview_id = "def456..."  # Dev

[[kv_namespaces]]
binding = "RATE_LIMIT"
id = "ghi789..."

# Environment variables
[vars]
CACHE_TTL = "86400"
RATE_LIMIT_REQUESTS = "100"
RATE_LIMIT_WINDOW = "3600"

# Secrets (set via `wrangler secret put`)
# API_KEY, DATABASE_URL, etc.

# Cron triggers
[triggers]
crons = ["0 */6 * * *"]  # Every 6 hours

# Custom routes
# routes = [{ pattern = "api.example.com/*", zone_name = "example.com" }]
```

## KV Storage Patterns

### Basic KV Operations

```typescript
// Write with TTL
await env.CACHE.put('key', JSON.stringify(data), {
  expirationTtl: 86400, // 24 hours in seconds
});

// Write with metadata
await env.CACHE.put('key', value, {
  expirationTtl: 3600,
  metadata: { createdAt: Date.now(), source: 'api' },
});

// Read
const value = await env.CACHE.get('key');
const parsed = await env.CACHE.get('key', 'json');

// Read with metadata
const { value, metadata } = await env.CACHE.getWithMetadata('key', 'json');

// Delete
await env.CACHE.delete('key');

// List keys
const { keys, cursor } = await env.CACHE.list({ prefix: 'meetings:' });
```

### Geohash-Based Caching

```typescript
import Geohash from 'latlon-geohash';

function getCacheKey(lat: number, lng: number, radius: number): string {
  // 3-char geohash = ~150km cells, good for metro areas
  const geohash = Geohash.encode(lat, lng, 3);
  return `meetings:${geohash}:${radius}`;
}

async function getMeetingsWithCache(
  lat: number,
  lng: number,
  radius: number,
  env: Env
): Promise<{ data: Meeting[]; cached: boolean; geohash: string }> {
  const geohash = Geohash.encode(lat, lng, 3);
  const cacheKey = `meetings:${geohash}:${radius}`;

  // Try cache first
  const cached = await env.MEETING_CACHE.get(cacheKey, 'json');
  if (cached) {
    return { data: cached, cached: true, geohash };
  }

  // Fetch fresh data
  const data = await fetchMeetings(lat, lng, radius);

  // Cache in background (don't await)
  env.ctx.waitUntil(
    env.MEETING_CACHE.put(cacheKey, JSON.stringify(data), {
      expirationTtl: 86400,
      metadata: { cachedAt: Date.now(), geohash },
    })
  );

  return { data, cached: false, geohash };
}
```

### Response Headers for Cache Debugging

```typescript
function meetingsResponse(data: Meeting[], cached: boolean, geohash: string): Response {
  return new Response(JSON.stringify(data), {
    headers: {
      ...CORS_HEADERS,
      'Content-Type': 'application/json',
      'X-Cache': cached ? 'HIT' : 'MISS',
      'X-Geohash': geohash,
      'Cache-Control': 'public, max-age=3600',
    },
  });
}
```

## Rate Limiting

### IP-Based Rate Limiting

```typescript
interface RateLimitConfig {
  maxRequests: number;
  windowSeconds: number;
}

async function checkRateLimit(
  ip: string,
  env: Env,
  config: RateLimitConfig
): Promise<{ allowed: boolean; remaining: number; resetAt: number }> {
  const key = `rate:${ip}`;
  const now = Math.floor(Date.now() / 1000);
  const windowStart = now - config.windowSeconds;

  // Get current state
  const stored = await env.RATE_LIMIT.get(key, 'json') as {
    count: number;
    windowStart: number;
  } | null;

  // New window or expired
  if (!stored || stored.windowStart < windowStart) {
    await env.RATE_LIMIT.put(key, JSON.stringify({
      count: 1,
      windowStart: now,
    }), { expirationTtl: config.windowSeconds });

    return {
      allowed: true,
      remaining: config.maxRequests - 1,
      resetAt: now + config.windowSeconds,
    };
  }

  // Within window
  if (stored.count >= config.maxRequests) {
    return {
      allowed: false,
      remaining: 0,
      resetAt: stored.windowStart + config.windowSeconds,
    };
  }

  // Increment
  await env.RATE_LIMIT.put(key, JSON.stringify({
    count: stored.count + 1,
    windowStart: stored.windowStart,
  }), { expirationTtl: config.windowSeconds });

  return {
    allowed: true,
    remaining: config.maxRequests - stored.count - 1,
    resetAt: stored.windowStart + config.windowSeconds,
  };
}

// Usage in handler
async function handleAPI(request: Request, env: Env): Promise<Response> {
  const ip = request.headers.get('CF-Connecting-IP') || 'unknown';
  const rateLimit = await checkRateLimit(ip, env, {
    maxRequests: parseInt(env.RATE_LIMIT_REQUESTS || '100'),
    windowSeconds: parseInt(env.RATE_LIMIT_WINDOW || '3600'),
  });

  if (!rateLimit.allowed) {
    return json({ error: 'Rate limit exceeded' }, 429, {
      'X-RateLimit-Remaining': '0',
      'X-RateLimit-Reset': rateLimit.resetAt.toString(),
    });
  }

  // ... handle request
}
```

## Durable Objects (Real-Time)

### Chat Room Example

```typescript
// wrangler.toml
// [[durable_objects.bindings]]
// name = "CHAT_ROOMS"
// class_name = "ChatRoom"
// [[migrations]]
// tag = "v1"
// new_classes = ["ChatRoom"]

export class ChatRoom {
  state: DurableObjectState;
  sessions: WebSocket[] = [];

  constructor(state: DurableObjectState) {
    this.state = state;
  }

  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === '/websocket') {
      if (request.headers.get('Upgrade') !== 'websocket') {
        return new Response('Expected WebSocket', { status: 400 });
      }

      const [client, server] = Object.values(new WebSocketPair());

      server.accept();
      this.sessions.push(server);

      server.addEventListener('message', (event) => {
        this.broadcast(event.data as string, server);
      });

      server.addEventListener('close', () => {
        this.sessions = this.sessions.filter(s => s !== server);
      });

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

    return new Response('Not found', { status: 404 });
  }

  broadcast(message: string, exclude?: WebSocket) {
    this.sessions.forEach(session => {
      if (session !== exclude && session.readyState === WebSocket.OPEN) {
        session.send(message);
      }
    });
  }
}

// In main worker
export default {
  async fetch(request: Request, env: Env) {
    const url = new URL(request.url);

    if (url.pathname.startsWith('/room/')) {
      const roomId = url.pathname.split('/')[2];
      const id = env.CHAT_ROOMS.idFromName(roomId);
      const room = env.CHAT_ROOMS.get(id);
      return room.fetch(request);
    }
  }
};
```

## Deployment & Debugging

### Commands

```bash
# Development
npx wrangler dev                    # Local dev server
npx wrangler dev --remote           # Dev against real KV/DO

# Deployment
npx wrangler deploy                 # Deploy to production
npx wrangler deploy --env staging   # Deploy to staging

# Secrets
npx wrangler secret put API_KEY     # Set secret
npx wrangler secret list            # List secrets

# KV Management
npx wrangler kv:key list --namespace-id=xxx
npx wrangler kv:key get --namespace-id=xxx "key"
npx wrangler kv:key delete --namespace-id=xxx "key"

# Logs
npx wrangler tail                   # Real-time logs
npx wrangler tail --format=pretty   # Formatted output
```

### Error Codes

| Code | Meaning |
|------|---------|
| 1101 | Worker threw exception |
| 1102 | CPU time limit exceeded |
| 1015 | Rate limited by Cloudflare |
| 524 | Origin timeout (&gt;100s) |

## Quick Reference

```typescript
// Get client IP
const ip = request.headers.get('CF-Connecting-IP');

// Get country
const country = request.cf?.country;

// Background task (won't block response)
ctx.waitUntil(doBackgroundWork());

// Streaming response
return new Response(readableStream, {
  headers: { 'Content-Type': 'text/event-stream' }
});

// Proxy request
const response = await fetch(upstreamUrl, request);
return new Response(response.body, response);
```

## Anti-Patterns

### ❌ Awaiting KV writes in hot path

```typescript
// ❌ ANTI-PATTERN: Blocks response on cache write
async function handler(request: Request, env: Env) {
  const data = await fetchData();
  await env.CACHE.put('key', data);  // Unnecessary wait!
  return json(data);
}

// ✅ CORRECT: Background write with waitUntil
async function handler(request: Request, env: Env, ctx: ExecutionContext) {
  const data = await fetchData();
  ctx.waitUntil(env.CACHE.put('key', data));  // Non-blocking
  return json(data);
}
```

### ❌ Missing CORS handling

```typescript
// ❌ ANTI-PATTERN: No preflight handling = broken browser requests
export default {
  async fetch(request: Request) {
    return json({ data: 'hello' });  // OPTIONS requests fail!
  }
}

// ✅ CORRECT: Handle OPTIONS preflight
export default {
  async fetch(request: Request) {
    if (request.method === 'OPTIONS') {
      return new Response(null, { status: 204, headers: CORS_HEADERS });
    }
    return json({ data: 'hello' });
  }
}
```

### ❌ Secrets in wrangler.toml

```toml
# ❌ ANTI-PATTERN: Secrets in config (committed to git!)
[vars]
API_KEY = "sk-live-xxxxx"

# ✅ CORRECT: Use wrangler secret
# Run: npx wrangler secret put API_KEY
# Access: env.API_KEY
```

### ❌ Ignoring KV eventual consistency

```typescript
// ❌ ANTI-PATTERN: Read immediately after write
await env.KV.put('count', String(newCount));
const verify = await env.KV.get('count');  // May return old value!

// ✅ CORRECT: Trust write succeeded, or use Durable Objects for consistency
await env.KV.put('count', String(newCount));
return json({ count: newCount });  // Return what you wrote
```

### ❌ Blocking on external APIs without timeout

```typescript
// ❌ ANTI-PATTERN: External API can hang your worker
const data = await fetch('https://slow-api.com/data');

// ✅ CORRECT: Add timeout with AbortController
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 5000);
try {
  const data = await fetch('https://slow-api.com/data', {
    signal: controller.signal
  });
} finally {
  clearTimeout(timeout);
}
```

## References

See `/references/` for detailed guides:
- `kv-patterns.md` - Advanced KV usage patterns
- `durable-objects.md` - Real-time features with DO
- `debugging.md` - Troubleshooting common issues

© curiositech · MIT · curiositech/some_claude_skills

Similar skills

All skills for DevOps and infrastructure →

From the same set180

The whole set →
launch-readiness-auditor launch-readiness-auditor audits codebases for production readiness before launch. It calculates a health score across eight areas and creates a prioritized two-week sprint plan. CX Codex +1 190installs postgresql-optimization postgresql-optimization helps identify PostgreSQL bottlenecks: interprets EXPLAIN ANALYZE plans, selects indexing strategies, and tunes parameters like shared_buffers and work_mem. CX Codex +1 190installs wedding-immortalist The wedding-immortalist skill outlines a workflow for turning wedding photos and video into 3D scenes, a guest roster, and selected highlights. Use it to plan an interactive wedding archive. CX Codex +1 190installs 2000s-visualization-expert 2000s-visualization-expert — a skill for rebuilding 2000s music visualizers — Milkdrop, AVS, Geiss — with WebGL and Web Audio. Use it when a player needs an audio-reactive backdrop or generative art driven by music. CX Codex +1 190installs clip-aware-embeddings clip-aware-embeddings guides AI coding agents to pick CLIP or dedicated computer vision models. It stops agents from misusing CLIP for counting or spatial reasoning. CX Codex +1 188installs code-necromancer The code-necromancer skill maps an inherited or dormant codebase, helps get it running, and lays out a modernization plan. It starts by examining the system before changing it. CX Codex +1 187installs vercel-deployment vercel-deployment — a skill that handles Vercel deploys for Next.js and React apps: env vars, edge functions, build fixes, preview deployments. Not for AWS, GCP or Azure. CX Codex +1 187installs speech-pathology-ai speech-pathology-ai guides coding assistants through speech therapy tools, acoustic phoneme inspection, and AAC systems. Helps build clinical practice software. CX Codex +1 186installs

Project sponsors

Companies that keep this analytics open