cloudflare-workers
Comprehensive guide for building serverless applications with Cloudflare Workers. Use when developing Workers, configuring bindings, implementing runtime APIs, testing Workers, using Wrangler CLI, deploying to production, or building edge functions with JavaScript/TypeScript/Python/Rust.
- Category: discovered
- Tags: github, community
- Version: 1.0.0
- Author: walid
- Downloads: 0
- Updated: 2025-11-22
Download the latest version (v1.0.0) from this page.
SKILL.md
---
name: cloudflare-workers
description: Comprehensive guide for building serverless applications with Cloudflare Workers. Use when developing Workers, configuring bindings, implementing runtime APIs, testing Workers, using Wrangler CLI, deploying to production, or building edge functions with JavaScript/TypeScript/Python/Rust.
license: MIT
version: 1.0.0
---
# Cloudflare Workers Skill
Cloudflare Workers is a serverless execution environment that runs JavaScript, TypeScript, Python, and Rust code on Cloudflare's global edge network across 300+ cities worldwide.
## Reference
- Main Documentation: https://developers.cloudflare.com/workers/
- Runtime APIs: https://developers.cloudflare.com/workers/runtime-apis/
- Examples: https://developers.cloudflare.com/workers/examples/
- Wrangler CLI: https://developers.cloudflare.com/workers/wrangler/
## When to Use This Skill
Use this skill when:
- Creating new Cloudflare Workers applications
- Configuring Worker bindings (D1, KV, R2, Durable Objects, etc.)
- Implementing Worker runtime APIs (fetch, cache, HTMLRewriter, WebSockets)
- Writing and testing Workers locally with Wrangler
- Deploying Workers to production
- Implementing cron triggers and scheduled jobs
- Building API endpoints and middleware
- Working with Workers static assets
- Setting up CI/CD for Workers
- Migrating from service workers to ES modules
- Debugging and monitoring Workers
- Optimizing Worker performance
## Core Concepts
### Execution Model
**V8 Isolates**: Workers run in lightweight V8 isolates (not containers):
- **Millisecond cold starts** (faster than containers)
- **Zero infrastructure management**
- **Automatic global scaling**
- **Pay-per-request pricing**
**Request Lifecycle**:
1. Request arrives at nearest Cloudflare data center
2. Worker executes in V8 isolate
3. Response returned to client
4. Isolate may be reused for subsequent requests
**Key Characteristics**:
- Maximum CPU time: 50ms (Free), 30 seconds (Paid)
- Maximum memory: 128MB
- Executes at the edge (closest to user)
- No state between requests (use Durable Objects for state)
### Worker Formats
**ES Modules (Recommended)**:
```typescript
// Modern syntax with export default
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
return new Response('Hello World!');
}
};
```
**Service Worker (Legacy)**:
```javascript
// Legacy format
addEventListener('fetch', (event) => {
event.respondWith(new Response('Hello World!'));
});
```
### Handler Types
Workers support multiple event types:
**Fetch Handler** (HTTP requests):
```typescript
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
return new Response('Hello');
}
};
```
**Scheduled Handler** (Cron jobs):
```typescript
export default {
async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext): Promise<void> {
// Runs on schedule
await fetch('https://api.example.com/cleanup');
}
};
```
**Queue Handler** (Message processing):
```typescript
export default {
async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext): Promise<void> {
for (const message of batch.messages) {
await processMessage(message.body);
}
}
};
```
**Email Handler** (Email routing):
```typescript
export default {
async email(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext): Promise<void> {
await message.forward('destination@example.com');
}
};
```
**Tail Handler** (Log aggregation):
```typescript
export default {
async tail(events: TraceItem[], env: Env, ctx: ExecutionContext): Promise<void> {
// Process logs from other Workers
}
};
```
## API Key Configuration
Cloudflare Workers require API credentials for CLI operations. The system searches for API keys in this order:
1. `process.env` - Runtime environment variables
2. `<project-root>/.env` - Project-level environment file
3. `.claude/.env` - Claude configuration directory
4. `.claude/skills/.env` - Skills shared configuration
5. `.claude/skills/cloudflare-workers/.env` - Skill-specific configuration
**Required Environment Variables:**
```bash
CLOUDFLARE_API_TOKEN=your_api_token_here
CLOUDFLARE_ACCOUNT_ID=your_account_id_here
```
**Where to Get Credentials:**
- API Token: Cloudflare Dashboard → My Profile → API Tokens → Create Token
- Use "Edit Cloudflare Workers" template for Workers-specific permissions
- Account ID: Cloudflare Dashboard → Overview → Account ID (right sidebar)
**Example .env File:**
```bash
# See .claude/skills/.env.example for complete configuration
CLOUDFLARE_API_TOKEN=abc123...
CLOUDFLARE_ACCOUNT_ID=def456...
```
## Wrangler CLI
### Installation & Setup
```bash
# Install globally
npm install -g wrangler
# Or use npx
npx wrangler <command>
# Login to Cloudflare
wrangler login
# Check version
wrangler --version
```
### Project Management
```bash
# Create new Worker
wrangler init my-worker
# Options: TypeScript, Git, deploy
# Create with template
wrangler init my-worker --template <template-url>
# Development server
wrangler dev # Local mode
wrangler dev --remote # Remote mode (actual edge)
wrangler dev --port 8080 # Custom port
# Deploy
wrangler deploy # Production
wrangler deploy --dry-run # Preview changes
wrangler deploy --env staging # Specific environment
# Logs
wrangler tail # Real-time logs
wrangler tail --format pretty # Formatted output
wrangler tail --status error # Filter by status
# Versions & Rollback
wrangler deployments list
wrangler rollback [version-id]
wrangler versions list
```
### Configuration (wrangler.toml)
```toml
name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-01-01"
compatibility_flags = ["nodejs_compat"]
# Routes
routes = [
{ pattern = "example.com/*", zone_name = "example.com" }
]
# Or use custom domains
# [[routes]]
# pattern = "api.example.com/*"
# custom_domain = true
# Environment variables
[vars]
ENVIRONMENT = "production"
API_VERSION = "v1"
# Cron triggers
[triggers]
crons = ["0 0 * * *"] # Daily at midnight
# Build configuration
[build]
command = "npm run build"
watch_dirs = ["src"]
# Environments
[env.staging]
name = "my-worker-staging"
routes = [
{ pattern = "staging.example.com/*", zone_name = "example.com" }
]
[env.staging.vars]
ENVIRONMENT = "staging"
```
### Secrets Management
```bash
# Add secret
wrangler secret put API_KEY
# Enter value when prompted
# List secrets
wrangler secret list
# Delete secret
wrangler secret delete API_KEY
# Bulk upload
echo "VALUE" | wrangler secret put API_KEY
```
## Runtime APIs
### Fetch API
```typescript
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
// Parse URL
const url = new URL(request.url);
// Request properties
const method = request.method;
const headers = request.headers;
const body = await request.text();
// Subrequest
const response = await fetch('https://api.example.com/data', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ key: 'value' })
});
const data = await response.json();
// Response
return new Response(JSON.stringify(data), {
status: 200,
headers: {
'Content-Type': 'application/json',
'Cache-Control': 'public, max-age=3600'
}
});
}
};
```
### Headers API
```typescript
// Read headers
const userAgent = request.headers.get('User-Agent');
const allHeaders = Object.fromEntries(request.headers);
// Set headers
const headers = new Headers();
headers.set('Content-Type', 'application/json');
headers.append('X-Custom-Header', 'value');
// Cloudflare-specific headers
const country = request.cf?.country;
const colo = request.cf?.colo;
const clientIP = request.headers.get('CF-Connecting-IP');
// Response with headers
return new Response(body, { headers });
```
### Cache API
```typescript
export default {
async fetch(request: Request): Promise<Response> {
const cache = caches.default;
// Check cache
let response = await cache.match(request);
if (!response) {
// Cache miss - fetch from origin
response = await fetch(request);
// Clone and cache response
const cacheResponse = response.clone();
ctx.waitUntil(cache.put(request, cacheResponse));
}
return response;
}
};
```
**Cache with custom key**:
```typescript
const cacheKey = new Request(url.toString(), request);
const response = await cache.match(cacheKey);
if (!response) {
response = await fetch(request);
ctx.waitUntil(cache.put(cacheKey, response.clone()));
}
```
**Cache with TTL**:
```typescript
const response = await fetch('https://api.example.com/data', {
cf: {
cacheTtl: 3600,
cacheEverything: true,
cacheKey: 'custom-key'
}
});
```
### HTMLRewriter
```typescript
export default {
async fetch(request: Request): Promise<Response> {
const response = await fetch(request);
return new HTMLRewriter()
.on('title', {
element(element) {
element.setInnerContent('New Title');
}
})
.on('a[href]', {
element(element) {
const href = element.getAttribute('href');
element.setAttribute('href', href.replace('http://', 'https://'));
}
})
.on('script', {
element(element) {
element.remove();
}
})
.transform(response);
}
};
```
**Text manipulation**:
```typescript
new HTMLRewriter()
.on('p', {
text(text) {
if (text.text.includes('replace-me')) {
text.replace('new-text');
}
}
})
.transform(response);
```
### WebSockets
```typescript
export default {
async fetch(request: Request): Promise<Response> {
const upgradeHeader = request.headers.get('Upgrade');
if (upgradeHeader !== 'websocket') {
return new Response('Expected WebSocket', { status: 426 });
}
const pair = new WebSocketPair();
const [client, server] = Object.values(pair);
// Accept WebSocket connection
server.accept();
// Handle messages
server.addEventListener('message', (event) => {
server.send(`Echo: ${event.data}`);
});
server.addEventListener('close', () => {
console.log('WebSocket closed');
});
return new Response(null, {
status: 101,
webSocket: client
});
}
};
```
### Streams API
```typescript
// Readable stream
const { readable, writable } = new TransformStream();
const writer = writable.getWriter();
writer.write(new TextEncoder().encode('chunk 1'));
writer.write(new TextEncoder().encode('chunk 2'));
writer.close();
return new Response(readable, {
headers: { 'Content-Type': 'text/plain' }
});
```
**Stream transformation**:
```typescript
const response = await fetch('https://example.com/large-file');
const { readable, writable } = new TransformStream({
transform(chunk, controller) {
// Process chunk
controller.enqueue(chunk);
}
});
response.body.pipeTo(writable);
return new Response(readable);
```
### Context API
```typescript
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
// waitUntil: Run tasks after response sent
ctx.waitUntil(
fetch('https://analytics.example.com/log', {
method: 'POST',
body: JSON.stringify({ url: request.url })
})
);
// passThroughOnException: Continue to origin on error
ctx.passThroughOnException();
return new Response('OK');
}
};
```
### Web Crypto API
```typescript
// Generate hash
const data = new TextEncoder().encode('message');
const hashBuffer = await crypto.subtle.digest('SHA-256', data);
const hashArray = Array.from(new Uint8Array(hashBuffer));
const hashHex = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
// HMAC signature
const key = await crypto.subtle.importKey(
'raw',
new TextEncoder().encode('secret'),
{ name: 'HMAC', hash: 'SHA-256' },
false,
['sign', 'verify']
);
const signature = await crypto.subtle.sign('HMAC', key, data);
// Verify
const valid = await crypto.subtle.verify('HMAC', key, signature, data);
// Random values
const randomBytes = crypto.getRandomValues(new Uint8Array(32));
const uuid = crypto.randomUUID();
// Timing-safe comparison
const equal = crypto.timingSafeEqual(buffer1, buffer2);
```
## Bindings
### Environment Variables
```typescript
// wrangler.toml
[vars]
API_URL = "https://api.example.com"
// Usage
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const apiUrl = env.API_URL;
return new Response(apiUrl);
}
};
```
### KV Namespace
```toml
# wrangler.toml
[[kv_namespaces]]
binding = "MY_KV"
id = "your-namespace-id"
```
```typescript
export default {
async fetch(request: Request, env: Env): Promise<Response> {
// Put
await env.MY_KV.put('key', 'value', {
expirationTtl: 3600,
metadata: { userId: '123' }
});
// Get
const value = await env.MY_KV.get('key');
const json = await env.MY_KV.get('key', 'json');
const buffer = await env.MY_KV.get('key', 'arrayBuffer');
const stream = await env.MY_KV.get('key', 'stream');
// Get with metadata
const { value, metadata } = await env.MY_KV.getWithMetadata('key');
// Delete
await env.MY_KV.delete('key');
// List
const list = await env.MY_KV.list({ prefix: 'user:' });
return new Response(value);
}
};
```
### R2 Bucket
```toml
# wrangler.toml
[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "my-bucket"
```
```typescript
export default {
async fetch(request: Request, env: Env): Promise<Response> {
// Put object
await env.MY_BUCKET.put('file.txt', 'content', {
httpMetadata: {
contentType: 'text/plain',
contentLanguage: 'en-US',
cacheControl: 'public, max-age=3600'
},
customMetadata: {
uploadedBy: 'user123'
}
});
// Get object
const object = await env.MY_BUCKET.get('file.txt');
if (!object) {
return new Response('Not Found', { status: 404 });
}
// Return object
return new Response(object.body, {
headers: {
'Content-Type': object.httpMetadata?.contentType || 'application/octet-stream',
'ETag': object.etag
}
});
// Delete object
await env.MY_BUCKET.delete('file.txt');
// List objects
const listed = await env.MY_BUCKET.list({ prefix: 'uploads/' });
// Multipart upload
const multipart = await env.MY_BUCKET.createMultipartUpload('large-file.bin');
const part1 = await multipart.uploadPart(1, chunk1);
const part2 = await multipart.uploadPart(2, chunk2);
await multipart.complete([part1, part2]);
}
};
```
### D1 Database
```toml
# wrangler.toml
[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "your-database-id"
```
```typescript
export default {
async fetch(request: Request, env: Env): Promise<Response> {
// Query
const result = await env.DB.prepare(
'SELECT * FROM users WHERE id = ?'
).bind(userId).first();
// Insert
const info = await env.DB.prepare(
'INSERT INTO users (name, email) VALUES (?, ?)'
).bind('Alice', 'alice@example.com').run();
// Batch (atomic)
const results = await env.DB.batch([
env.DB.prepare('UPDATE accounts SET balance = balance - 100 WHERE id = ?').bind(1),
env.DB.prepare('UPDATE accounts SET balance = balance + 100 WHERE id = ?').bind(2)
]);
// All results
const { results: rows } = await env.DB.prepare(
'SELECT * FROM users'
).all();
return new Response(JSON.stringify(result));
}
};
```
### Durable Objects
```toml
# wrangler.toml
[[durable_objects.bindings]]
name = "COUNTER"
class_name = "Counter"
script_name = "my-worker"
```
```typescript
// Define Durable Object
export class Counter {
state: DurableObjectState;
constructor(state: DurableObjectState, env: Env) {
this.state = state;
}
async fetch(request: Request): Promise<Response> {
let count = (await this.state.storage.get<number>('count')) || 0;
count++;
await this.state.storage.put('count', count);
return new Response(JSON.stringify({ count }));
}
// Alarm handler
async alarm(): Promise<void> {
// Runs at scheduled time
await this.state.storage.deleteAll();
}
}
// Use in Worker
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const id = env.COUNTER.idFromName('global');
const counter = env.COUNTER.get(id);
return counter.fetch(request);
}
};
```
### Queues
```toml
# wrangler.toml
[[queues.producers]]
binding = "MY_QUEUE"
queue = "my-queue"
[[queues.consumers]]
queue = "my-queue"
max_batch_size = 10
max_batch_timeout = 30
```
```typescript
// Producer
export default {
async fetch(request: Request, env: Env): Promise<Response> {
await env.MY_QUEUE.send({
type: 'email',
to: 'user@example.com'
});
// Batch send
await env.MY_QUEUE.sendBatch([
{ body: { message: 1 } },
{ body: { message: 2 } }
]);
return new Response('Queued');
}
};
// Consumer
export default {
async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext): Promise<void> {
for (const message of batch.messages) {
try {
await processMessage(message.body);
message.ack();
} catch (error) {
message.retry();
}
}
}
};
```
### Workers AI
```toml
# wrangler.toml
[ai]
binding = "AI"
```
```typescript
export default {
async fetch(request: Request, env: Env): Promise<Response> {
// Text generation
const response = await env.AI.run('@cf/meta/llama-3-8b-instruct', {
messages: [
{ role: 'user', content: 'What is edge computing?' }
]
});
// Image generation
const imageResponse = await env.AI.run('@cf/stabilityai/stable-diffusion-xl-base-1.0', {
prompt: 'A sunset over mountains'
});
// Embeddings
const embeddings = await env.AI.run('@cf/baai/bge-base-en-v1.5', {
text: ['Hello world', 'Cloudflare Workers']
});
// Speech recognition
const audio = await request.arrayBuffer();
const transcription = await env.AI.run('@cf/openai/whisper', {
audio: [...new Uint8Array(audio)]
});
return new Response(JSON.stringify(response));
}
};
```
### Vectorize (Vector Database)
```toml
# wrangler.toml
[[vectorize]]
binding = "VECTORIZE_INDEX"
index_name = "my-index"
```
```typescript
export default {
async fetch(request: Request, env: Env): Promise<Response> {
// Insert vectors
await env.VECTORIZE_INDEX.insert([
{
id: '1',
values: [0.1, 0.2, 0.3],
metadata: { text: 'Hello world' }
}
]);
// Query
const results = await env.VECTORIZE_INDEX.query(
[0.1, 0.2, 0.3],
{ topK: 5 }
);
return new Response(JSON.stringify(results));
}
};
```
## Development Patterns
### Routing
```typescript
export default {
async fetch(request: Request): Promise<Response> {
const url = new URL(request.url);
// Route by path
switch (url.pathname) {
case '/':
return new Response('Home');
case '/about':
return new Response('About');
default:
return new Response('Not Found', { status: 404 });
}
}
};
```
**Using Hono framework**:
```typescript
import { Hono } from 'hono';
const app = new Hono();
app.get('/', (c) => c.text('Home'));
app.get('/api/users/:id', async (c) => {
const id = c.req.param('id');
const user = await getUser(id);
return c.json(user);
});
export default app;
```
### Middleware Pattern
```typescript
async function auth(request: Request, env: Env): Promise<Response | null> {
const token = request.headers.get('Authorization');
if (!t