cloudflare-worker

Cloudflare Workers

Development patterns for TypeScript Workers.

Related skills (majestic-devops):

• wrangler-coder: CLI deployment, secrets, testing, multi-environment
• cloudflare-coder: Infrastructure provisioning with Terraform/OpenTofu

Core Principles

Edge-First Thinking

• Stateless by default: Workers don't persist state between requests
• Global distribution: Code runs in 300+ data centers worldwide
• Cold start optimized: V8 isolates start in milliseconds
• Request/response model: Each invocation handles one request

Storage Selection

Storage	Use Case	Consistency	Latency
KV	Config, flags, cached data	Eventually consistent	~10ms
D1	Relational data, transactions	Strong (single region)	~30-50ms
R2	Files, images, large objects	Strong	~50-100ms
Durable Objects	Real-time state, WebSockets	Strong (per-object)	~50ms
Queues	Async processing, batching	At-least-once	Async

Project Structure

my-worker/
├── src/
│   ├── index.ts          # Entry point
│   ├── routes/           # Route handlers
│   ├── services/         # Business logic
│   └── types.ts          # Type definitions
├── test/
├── wrangler.toml         # Cloudflare config
├── package.json
└── tsconfig.json

Quick Start

Minimal wrangler.toml

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-12-01"
compatibility_flags = ["nodejs_compat"]

See references/setup.md for full configuration with all bindings.

Basic Hono App

import { Hono } from 'hono';
import { Env } from './types';

const app = new Hono<{ Bindings: Env }>();

app.get('/', (c) => c.json({ status: 'ok' }));
app.onError((err, c) => c.json({ error: 'Internal Error' }, 500));
app.notFound((c) => c.json({ error: 'Not Found' }, 404));

export default app;

See references/hono.md for route organization and middleware patterns.

Storage Quick Reference

KV (Key-Value)

await env.CACHE.get('key', 'json');
await env.CACHE.put('key', value, { expirationTtl: 3600 });
await env.CACHE.delete('key');

D1 (SQLite)

const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?')
  .bind(id).first();

R2 (Object Storage)

await env.STORAGE.put('path/file.json', JSON.stringify(data));
const object = await env.STORAGE.get('path/file.json');

See references/storage.md for caching patterns, migrations, and queries.

Durable Objects

Use for: real-time coordination, WebSockets, rate limiting, distributed locks.

// Get DO stub
const id = c.env.COUNTER.idFromName('my-counter');
const stub = c.env.COUNTER.get(id);
const response = await stub.fetch(new Request('http://do/increment'));

See references/durable-objects.md for full patterns including WebSocket Hibernation.

Queues

// Producer
await env.QUEUE.send({ type: 'email', payload: { to: 'user@example.com' } });

// Consumer (add to default export)
async queue(batch: MessageBatch, env: Env) {
  for (const msg of batch.messages) {
    try { await process(msg.body); msg.ack(); }
    catch { msg.retry(); }
  }
}

See references/queues-testing.md for consumer patterns and testing setup.

CLI Commands

# Development
wrangler dev                    # Start local server
wrangler dev --remote           # Dev with remote bindings

# Deploy
wrangler deploy

# D1
wrangler d1 migrations apply my-database

# Secrets
wrangler secret put API_KEY

# Logs
wrangler tail

Anti-Patterns

Don't	Do Instead
Service Worker format	ES modules
await cache writes	waitUntil for non-blocking
Large KV values (>25MB)	R2 for files
server.accept() for WebSockets	ctx.acceptWebSocket() (Hibernation API)
Block on analytics/logging	waitUntil for background tasks
Assume KV immediate consistency	D1 or DOs for consistency-critical

Resources

• Cloudflare Workers Docs
• Hono Documentation
• D1 Documentation
• Durable Objects Guide