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
npx skills add curiositech/some_claude_skills --skill cloudflare-worker-dev -a claude-codeWhat 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
/healthroute and CORS handling. - Set up KV caching in
src/index.tsand add the bindings towrangler.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-code2Manually: put the files in place
~/.claude/skills/cloudflare-worker-dev/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/cloudflare-worker-dev/
1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill cloudflare-worker-dev -a codex2Manually: put the files in place
.agents/skills/cloudflare-worker-dev/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill cloudflare-worker-dev -a cursor2Manually: put the files in place
.cursor/skills/cloudflare-worker-dev/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install curiositech/some_claude_skills .claude/skills/cloudflare-worker-dev2Manually: put the files in place
.github/skills/cloudflare-worker-dev/SKILL.md1Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill cloudflare-worker-dev -a gemini-cli2Platform CLI
gemini skills install https://github.com/curiositech/some_claude_skills --path .claude/skills/cloudflare-worker-devManually: put the files in place
.devin/skills/cloudflare-worker-dev/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add curiositech/some_claude_skills --skill cloudflare-worker-dev -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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 (>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