Getting Started: wrangler CLI and Project Structure
The wrangler CLI is the sole tool for Workers development. It handles scaffolding, local dev server, binding configuration, and deployment.
# Install wrangler globally
npm install -g wrangler
# Authenticate with your Cloudflare account
wrangler login
# Scaffold a new TypeScript Worker
wrangler init my-worker --yes
The scaffolded project has src/index.ts (Worker entry point), wrangler.toml (configuration: bindings, routes, KV namespaces), package.json, and tsconfig.json. The wrangler.toml file is where all runtime bindings are declared — KV namespaces, D1 databases, R2 buckets, environment variables. Wrangler enforces that every binding used in code is declared here; undeclared bindings throw a TypeScript error at build time.
Local development runs with wrangler dev. Add --remote to test against real KV data or D1 databases. Local mode mocks bindings in memory — fast for iteration, but it does not catch quota or permission issues. Deployment is wrangler deploy — the process takes 3–8 seconds and deploys globally with no region selection or health check wait. For teams managing deployment cadence, the cron expression builder is useful for configuring Workers cron triggers in wrangler.toml.
Core Handler: The fetch Event
Every Worker exports a default object with a fetch handler. This is the entry point for all HTTP requests:
export interface Env {
MY_KV: KVNamespace
API_SECRET: string
}
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
const url = new URL(request.url)
if (url.pathname === '/health') {
return new Response('ok', { status: 200 })
}
if (url.pathname.startsWith('/api/')) {
return handleApi(request, env)
}
return new Response('Not Found', { status: 404 })
},
} satisfies ExportedHandler<Env>
The Env interface is where TypeScript type safety over bindings lives. The ctx.waitUntil() method on ExecutionContext is how you run fire-and-forget work (logging, analytics) without blocking the response.
Key APIs: KV, D1, R2, and Durable Objects
Workers’ storage APIs cover four distinct use cases. KV is globally replicated with eventual consistency — ideal for configuration data, feature flags, cached API responses, and URL mappings. D1 is Cloudflare’s distributed SQLite, supporting full SQL with prepared statements, out of beta in 2026. R2 is S3-compatible object storage with zero egress fees, eliminating the transfer costs that make S3 expensive at scale. Durable Objects provide strongly consistent state co-located with compute, always running in a single location globally for rate limiters, chat rooms, and booking systems.
// KV: read and write
const value = await env.MY_KV.get('key')
await env.MY_KV.put('key', 'value', { expirationTtl: 86400 })
// D1: prepared statement query
const result = await env.DB
.prepare('SELECT * FROM urls WHERE short_code = ?')
.bind(code)
.first<{ original_url: string }>()
// R2: serve an object
const obj = await env.BUCKET.get(key)
if (!obj) return new Response('Not Found', { status: 404 })
return new Response(obj.body, {
headers: { 'Content-Type': obj.httpMetadata?.contentType ?? 'application/octet-stream' },
})
Durable Objects are available on the Workers Paid plan only — not part of the free tier.
Real Example: URL Shortener in 50 Lines
This is a complete, production-ready URL shortener using Workers + KV:
export interface Env { URLS: KVNamespace }
function generateCode(length = 6): string {
const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'
return Array.from(crypto.getRandomValues(new Uint8Array(length)))
.map((b) => chars[b % chars.length])
.join('')
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const url = new URL(request.url)
if (request.method === 'POST' && url.pathname === '/shorten') {
const { originalUrl } = await request.json<{ originalUrl: string }>()
if (!originalUrl || !URL.canParse(originalUrl)) {
return new Response('Invalid URL', { status: 400 })
}
const code = generateCode()
await env.URLS.put(code, originalUrl, { expirationTtl: 60 * 60 * 24 * 365 })
return new Response(
JSON.stringify({ shortUrl: `${url.origin}/${code}` }),
{ headers: { 'Content-Type': 'application/json' } }
)
}
if (request.method === 'GET' && url.pathname.length > 1) {
const code = url.pathname.slice(1)
const originalUrl = await env.URLS.get(code)
if (!originalUrl) return new Response('Not Found', { status: 404 })
return Response.redirect(originalUrl, 301)
}
return new Response('Not Found', { status: 404 })
},
} satisfies ExportedHandler<Env>
Wire up the KV binding in wrangler.toml with [[kv_namespaces]], run wrangler kv namespace create URLS to get your namespace ID, and deploy. The entire workflow takes under 10 minutes. For managing environment variables between local dev and production, the env file converter handles the .env to wrangler.toml format conversion cleanly.
Cloudflare’s published cold start numbers for Workers in 2026 are under 5ms globally.
The cold start advantage is structural, not accidental. Lambda must boot a microVM (a Firecracker VM), initialize the Node.js runtime, and load your function bundle before executing. Workers skip all three steps — the V8 engine is always running, and isolate creation is measured in microseconds. Vercel Edge Functions share the same architecture; the meaningful differences are pricing and the depth of the Cloudflare storage/compute ecosystem.
Pricing at Scale: Workers Paid Plan
The Workers Paid plan costs $5/month and includes 10 million requests/month (then $0.30/million), 30ms CPU time per request, Durable Objects access, and expanded KV/D1/R2 quotas. At 10 million requests/month, $5 is $0.0000005 per request. AWS Lambda at comparable volume runs $0.0000002 for compute alone — before API Gateway ($3.50/million), data transfer, and CloudWatch. When total cost of ownership is counted, Workers Paid is cost-competitive with Lambda for the workloads it handles.
The break-even point: any production workload above 100K requests/day on average, or any project requiring Durable Objects or more than 1,000 KV writes/day.
Workers AI: Run ML Models at the Edge
Workers AI runs Cloudflare-hosted models — Llama 3.1, Mistral, Stable Diffusion, Whisper, and others — directly inside a Worker without an external inference API call.
export interface Env { AI: Ai }
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const { prompt } = await request.json<{ prompt: string }>()
const result = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
messages: [
{ role: 'system', content: 'You are a concise technical assistant.' },
{ role: 'user', content: prompt },
],
})
return new Response(JSON.stringify(result), {
headers: { 'Content-Type': 'application/json' },
})
},
} satisfies ExportedHandler<Env>
Workers AI latency for Llama 3.1 8B averages 200–400ms for typical prompt lengths — comparable to hosted inference APIs. The use case is not replacing frontier model API calls for complex reasoning. It is running inference for classification, summarization, or simple generation tasks without adding an external dependency or cross-region latency. For teams building production agentic pipelines, Cloudflare’s Agents Week 2026 guide covers the agent memory and state management APIs built on top of Durable Objects.
Use Cases and Caveats
Workers are the right tool for API routing and middleware (auth checks, rate limiting, header injection at the edge with no origin round-trip), A/B testing (traffic splitting by cookie, geo, or user-agent), bot detection (request pattern analysis with Cloudflare threat intelligence via the cf object on the request), redirect rules at scale (KV-backed marketing redirect tables — the JSON formatter helps validate mapping files before import), and image optimization (resize, WebP/AVIF conversion via the Image Resizing API on Paid). For multi-service agentic workflows, the Cloudflare + Stripe agent provisioning guide covers Workers in payment and provisioning pipelines.
Three constraints matter in practice. The 128MB memory limit per isolate is a hard ceiling — Workers are designed for stateless request processing, not large in-memory data structures; restructure to use KV instead of in-memory state for large lookup tables. No native Node.js modules: fs, net, dns, child_process are unavailable; audit npm dependency compatibility with wrangler deploy --dry-run before committing to a Workers architecture. CPU time limits are strict: 10ms free, 30ms Paid, no burst headroom — delegate heavy computation to D1, KV, or external APIs rather than doing it inline.
Ship Your First Worker Today
The full Workers stack — wrangler, KV, D1, R2, Workers AI — is production-ready in 2026. The free tier handles real production workloads. The Paid tier at $5/month scales to 10 million monthly requests.
Start with wrangler init, build the URL shortener above, and deploy it. The global deployment takes under 10 seconds. When you need persistence, wire in KV for simple lookups or D1 for structured queries. When you hit the limits of stateless isolates, Durable Objects are the path forward.
Every product mentioned in this guide is part of the broader WOWHOW developer toolkit — pay once, ship forever. See wowhow.cloud for premium tools and templates that accelerate edge-first production architectures.
Comments · 0
Beta: comments are stored locally on your device and not visible to other readers.
No comments yet. Be the first to share your thoughts.