Cloudflare
Overview
Cloudflare Workers is a serverless edge compute platform that runs JavaScript, TypeScript, and WebAssembly on Cloudflare's global network. Workers use the ES modules format with fetch, scheduled, and queue event handlers, and access platform services (KV, D1, R2, Durable Objects) through environment bindings.
When to use: Edge-first APIs, low-latency global apps, serverless functions, static site hosting with Pages, key-value caching, relational data at the edge, object storage without egress fees.
When NOT to use: Long-running compute exceeding CPU time limits, workloads requiring persistent TCP connections, applications needing full Node.js API compatibility, large monolithic applications better suited to containers.
Quick Reference
| Pattern | API / Config | Key Points |
|---|---|---|
| Fetch handler | export default {fetch(request, env, ctx)} | Entry point for HTTP requests |
| Scheduled handler | export default {scheduled(controller, env, ctx)} | Cron triggers via [triggers] in config |
| Environment variables | env.VAR_NAME | Set in wrangler.toml or dashboard |
| KV read/write | env.KV.get(key) / env.KV.put(key, value) | Eventually consistent, 25 MiB max value |
| D1 query | env.DB.prepare(sql).bind(...params).all() | SQLite at the edge, prepared statements |
| D1 batch | env.DB.batch([stmt1, stmt2]) | Atomic transaction, single round trip |
| R2 upload | env.BUCKET.put(key, body) | S3-compatible, no egress fees |
| R2 download | env.BUCKET.get(key) | Returns R2ObjectBody with ReadableStream |
| Durable Objects | env.DO.get(id) then stub.fetch(request) | Single-instance stateful coordination |
| DO storage | this.ctx.storage.sql.exec(query) | SQLite backend recommended for new DOs |
| Pages deploy | wrangler pages deploy <dir> | Static + Functions, auto-generated routes |
| Worker deploy | wrangler deploy | Reads wrangler.toml for config |
| Dev server | wrangler dev | Local development with bindings |
| Secrets | wrangler secret put SECRET_NAME | Encrypted, not in wrangler.toml |
| Static assets | assets: {directory: "./dist"} | Served without invoking Worker by default |
| Workflows | export class MyWorkflow extends WorkflowEntrypoint | Durable multi-step execution engine |
| Hyperdrive | env.HYPERDRIVE.connectionString | Connection pooling for external PostgreSQL |
| Queues produce | env.QUEUE.send(message) | Async message passing between Workers |
| Config format | wrangler.jsonc (recommended for new projects) | JSON with comments; preferred over TOML |
Common Mistakes
| Mistake | Correct Pattern |
|---|---|
| Accessing bindings as globals | Access via env parameter in module format |
| Storing secrets in wrangler.toml | Use wrangler secret put for encrypted values |
| Using KV for strong consistency | Use D1 or Durable Objects for consistent reads |
| Not binding parameters in D1 queries | Always use .prepare().bind() to prevent SQL injection |
| Exceeding KV value size (25 MiB) | Use R2 for objects larger than 25 MiB |
Forgetting await on storage operations | KV, D1, R2 methods are all async |
Using fetch() without passing signal | Pass request.signal for automatic cancellation |
| Creating D1 database in Worker code | Create with wrangler d1 create, bind in config |
Missing compatibility_date in config | Always set to avoid breaking changes |
| Returning non-Response from fetch handler | Must return a Response object |
Using wrangler.toml for new projects | Use wrangler.jsonc for new projects; has better IDE support |
| Using KV for relational queries | Use D1 for SQL queries; KV is key-value only |
Delegation
- Architecture review: Use
Taskagent to evaluate edge vs origin patterns - Code review: Delegate to
code-revieweragent - Storage selection: Use
Exploreagent to compare KV vs D1 vs R2 vs DO