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
// 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)
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
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
// 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
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
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
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
// 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
# 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
// 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
// ❌ 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
// ❌ 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
# ❌ 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
// ❌ 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
// ❌ 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 patternsdurable-objects.md- Real-time features with DOdebugging.md- Troubleshooting common issues