Agent skills
cloudflare-worker-dev

Agent skill

cloudflare-worker-dev

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.

View SKILL.md on GitHub Repository

Stars 81

Forks 12

Install this agent skill to your Project

npx add-skill https://github.com/curiositech/some_claude_skills/tree/main/.claude/skills/cloudflare-worker-dev

Metadata

Additional technical details for this skill

tags: cloudflare workers edge-computing serverless kv caching rate-limiting
category: DevOps & Site Reliability
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" } ]

SKILL.md

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

Maintainer

curiositech Core maintainer

Source details

Full Name: curiositech/some_claude_skills
Branch: main
Path in repo: .claude/skills/cloudflare-worker-dev
License: MIT License

Featured Tools

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

curiositech/some_claude_skills

3d-cv-labeling-2026

Expert in 3D computer vision labeling tools, workflows, and AI-assisted annotation for LiDAR, point clouds, and sensor fusion. Covers SAM4D/Point-SAM, human-in-the-loop architectures, and vertical-specific training strategies. Activate on '3D labeling', 'point cloud annotation', 'LiDAR labeling', 'SAM 3D', 'SAM4D', 'sensor fusion annotation', '3D bounding box', 'semantic segmentation point cloud'. NOT for 2D image labeling (use clip-aware-embeddings), general ML training (use ml-engineer), video annotation without 3D (use computer-vision-pipeline), or VLM prompt engineering (use prompt-engineer).

81 12

Explore

curiositech/some_claude_skills

project-management-guru-adhd

Expert project manager for ADHD engineers managing multiple concurrent projects. Specializes in hyperfocus management, context-switching minimization, and parakeet-style gentle reminders. Activate on 'ADHD project management', 'context switching', 'hyperfocus', 'task prioritization', 'multiple projects', 'productivity for ADHD', 'task chunking', 'deadline management'. NOT for neurotypical project management, rigid waterfall processes, or general productivity advice without ADHD context.

81 12

Explore

curiositech/some_claude_skills

large-scale-map-visualization

Master of high-performance web map implementations handling 5,000-100,000+ geographic data points. Specializes in Leaflet.js optimization, Supercluster algorithms, viewport-based loading, canvas rendering, and progressive disclosure UX patterns.

81 12

Explore

curiositech/some_claude_skills

adhd-design-expert

Designs digital experiences for ADHD brains using neuroscience research and UX principles. Expert in reducing cognitive load, time blindness solutions, dopamine-driven engagement, and compassionate design patterns. Activate on 'ADHD design', 'cognitive load', 'accessibility', 'neurodivergent UX', 'time blindness', 'dopamine-driven', 'executive function'. NOT for general accessibility (WCAG only), neurotypical UX design, or simple UI styling without ADHD context.

81 12

Explore

curiositech/some_claude_skills

liaison

Translate multi-agent ecosystem activity into human-readable status briefings, decision requests, and progress summaries. Use for 'status update', 'brief me', 'what happened', 'summarize progress'. NOT for project planning (use project-management-guru-adhd), code review, or technical documentation.

81 12

Explore

curiositech/some_claude_skills

windows-95-web-designer

Modern web applications with authentic Windows 95 aesthetic. Gradient title bars, Start menu paradigm, taskbar patterns, 3D beveled chrome. Extrapolates Win95 to AI chatbots, mobile UIs, responsive layouts. Activate on 'windows 95', 'win95', 'start menu', 'taskbar', 'retro desktop', '95 aesthetic', 'clippy'. NOT for Windows 3.1 (use windows-3-1-web-designer), vaporwave/synthwave, macOS, flat design.

81 12

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

Metadata

SKILL.md

Cloudflare Workers Development

Core Architecture

When to Use What

Worker Fundamentals

Basic Worker Structure

CORS Headers (Essential)

wrangler.toml Configuration

KV Storage Patterns

Basic KV Operations

Geohash-Based Caching

Response Headers for Cache Debugging

Rate Limiting

IP-Based Rate Limiting

Durable Objects (Real-Time)

Chat Room Example

Deployment & Debugging

Commands

Error Codes

Quick Reference

Anti-Patterns

❌ Awaiting KV writes in hot path

❌ Missing CORS handling

❌ Secrets in wrangler.toml

❌ Ignoring KV eventual consistency

❌ Blocking on external APIs without timeout

References

Recommended Agent Skills

3d-cv-labeling-2026

project-management-guru-adhd

large-scale-map-visualization

adhd-design-expert

liaison

windows-95-web-designer