Cloudflare Workers
Overview
Cloudflare Workers runs code at the edge in V8 isolates, with cold starts measured in low milliseconds. Workers pairs with storage and compute services: KV (eventually-consistent key-value cache), D1 (serverless SQLite), R2 (S3-compatible object storage with no egress fees), Durable Objects (strongly consistent, single-instance state), and Queues (message queues for background work). The CLI is Wrangler; configuration lives in wrangler.jsonc (or the older wrangler.toml).
Instructions
- Scaffold a new Worker with
npm create cloudflare@latest -- my-worker (the create-cloudflare CLI, "C3"). wrangler init still exists but C3 is what Cloudflare's own quickstart uses now.
- Write the Worker as an ES Module:
export default { async fetch(request, env, ctx) { ... } }. The older Service Worker syntax (addEventListener('fetch', ...)) still runs but is not recommended for new code.
- Always set
compatibility_date in wrangler.jsonc to pin runtime behavior to a known date; bump it deliberately when you want newer defaults.
- For storage, prefer D1 for relational/SQL data, KV for simple read-heavy key-value caching, R2 for object storage, and Durable Objects when you need a single strongly-consistent instance coordinating state (e.g. a WebSocket room or a rate limiter).
- Run
wrangler dev for local development; it simulates KV/D1/R2 locally by default and only touches real remote resources when you pass --remote.
- Deploy with
wrangler deploy. Routes, bindings and build settings live in wrangler.jsonc.
- Store secrets with
wrangler secret put SECRET_NAME (interactive prompt) — never put them in wrangler.jsonc. Type all bindings with an Env interface (TypeScript) generated by wrangler types.
- Create a KV namespace with
wrangler kv namespace create <BINDING_NAME> and copy the returned id into kv_namespaces in wrangler.jsonc. Create a D1 database with wrangler d1 create <NAME> and apply schema with wrangler d1 migrations apply <NAME>.
- For caching, use the Cache API (
caches.default), and for heavier HTML rewriting use HTMLRewriter. Use ctx.waitUntil() for fire-and-forget async work (analytics, logging) that should not block the response.
- Tail live logs with
wrangler tail.
Examples
Example 1: Edge API with KV caching
User request: "Set up a Cloudflare Worker that serves cached API responses from KV."
npm create cloudflare@latest -- product-cache-api
cd product-cache-api
npx wrangler kv namespace create PRODUCT_CACHE
// wrangler.jsonc
{
"name": "product-cache-api",
"main": "src/index.ts",
"compatibility_date": "2026-09-23",
"kv_namespaces": [
{ "binding": "PRODUCT_CACHE", "id": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d" }
]
}
// src/index.ts
export interface Env {
PRODUCT_CACHE: KVNamespace;
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const url = new URL(request.url);
const sku = url.searchParams.get("sku");
if (!sku) return new Response("Missing sku", { status: 400 });
const cached = await env.PRODUCT_CACHE.get(sku);
if (cached) return new Response(cached, { headers: { "Cache-Control": "public, max-age=60" } });
const upstream = await fetch(`https://api.internal.example/products/${sku}`);
const body = await upstream.text();
await env.PRODUCT_CACHE.put(sku, body, { expirationTtl: 300 });
return new Response(body, { headers: { "Cache-Control": "public, max-age=60" } });
},
};
npx wrangler dev # local, simulated KV
npx wrangler deploy
Output: a Worker that checks KV for a cached product, falls back to the origin API, and caches the result for five minutes.
Example 2: Scheduled sync into D1
User request: "Build a Worker that runs on a schedule to sync inventory counts from an external API into D1."
npx wrangler d1 create inventory-db
npx wrangler d1 migrations create inventory-db create_inventory_table
# edit the generated migration SQL, then:
npx wrangler d1 migrations apply inventory-db --remote
{
"d1_databases": [
{ "binding": "DB", "database_name": "inventory-db", "database_id": "7f3e9c21-4b8a-4d6e-9f12-5a6b7c8d9e0f" }
],
"triggers": { "crons": ["0 * * * *"] }
}
export default {
async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext) {
const res = await fetch("https://api.internal.example/inventory/snapshot");
const items: { sku: string; count: number }[] = await res.json();
const stmt = env.DB.prepare("INSERT OR REPLACE INTO inventory (sku, count) VALUES (?, ?)");
await env.DB.batch(items.map((i) => stmt.bind(i.sku, i.count)));
ctx.waitUntil(fetch("https://api.internal.example/sync/ack", { method: "POST" }));
},
};
Output: a cron-triggered Worker (hourly) that refreshes a D1 inventory table from an upstream API.
Guidelines
wrangler.jsonc is now the format Cloudflare recommends for new projects; some newer Wrangler features are JSON-only. wrangler.toml still works but migrate when convenient.- Use ES Module syntax over Service Worker syntax for new Workers.
- Type every environment binding with an
Env interface; run wrangler types to regenerate it after changing bindings.
- Handle errors with explicit HTTP status codes instead of letting exceptions produce an unhandled-error page.
- Prefer D1 for relational data; use KV only for simple, read-heavy caching where eventual consistency is acceptable.
wrangler dev without --remote simulates storage locally — don't assume local test data exists in production, or vice versa.- Secrets set with
wrangler secret put are per-environment; re-run it for staging and production separately if you use multiple environments.