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
Task agent to evaluate edge vs origin patterns
- Code review: Delegate to
code-reviewer agent
- Storage selection: Use
Explore agent to compare KV vs D1 vs R2 vs DO
References
- Workers syntax, fetch handler, scheduled events, and bindings
- KV, D1, R2, and Durable Objects storage APIs
- Cloudflare Pages, functions, routes, and build configuration
- Wrangler CLI, configuration, dev server, deploy, and secrets
1---2name: cloudflare3description: Cloudflare Workers, KV, D1, R2, Pages, and Wrangler CLI. Use when deploying to the edge, configuring Workers, managing storage bindings, or setting up Cloudflare Pages.4license: MIT5---6
7# Cloudflare
8
9## Overview
10
11Cloudflare 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.
12
13**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.
14
15**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.
16
17## Quick Reference
18
19| Pattern | API / Config | Key Points |
20| --------------------- | ---------------------------------------------------- | -------------------------------------------- |
21| Fetch handler | `export default { fetch(request, env, ctx) }` | Entry point for HTTP requests |
22| Scheduled handler | `export default { scheduled(controller, env, ctx) }` | Cron triggers via `[triggers]` in config |
23| Environment variables | `env.VAR_NAME` | Set in wrangler.toml or dashboard |
24| KV read/write | `env.KV.get(key)` / `env.KV.put(key, value)` | Eventually consistent, 25 MiB max value |
25| D1 query | `env.DB.prepare(sql).bind(...params).all()` | SQLite at the edge, prepared statements |
26| D1 batch | `env.DB.batch([stmt1, stmt2])` | Atomic transaction, single round trip |
27| R2 upload | `env.BUCKET.put(key, body)` | S3-compatible, no egress fees |
28| R2 download | `env.BUCKET.get(key)` | Returns `R2ObjectBody` with `ReadableStream` |
29| Durable Objects | `env.DO.get(id)` then `stub.fetch(request)` | Single-instance stateful coordination |
30| DO storage | `this.ctx.storage.sql.exec(query)` | SQLite backend recommended for new DOs |
31| Pages deploy | `wrangler pages deploy <dir>` | Static + Functions, auto-generated routes |
32| Worker deploy | `wrangler deploy` | Reads wrangler.toml for config |
33| Dev server | `wrangler dev` | Local development with bindings |
34| Secrets | `wrangler secret put SECRET_NAME` | Encrypted, not in wrangler.toml |
35| Static assets | `assets: { directory: "./dist" }` | Served without invoking Worker by default |
36| Workflows | `export class MyWorkflow extends WorkflowEntrypoint` | Durable multi-step execution engine |
37| Hyperdrive | `env.HYPERDRIVE.connectionString` | Connection pooling for external PostgreSQL |
38| Queues produce | `env.QUEUE.send(message)` | Async message passing between Workers |
39| Config format | `wrangler.jsonc` (recommended for new projects) | JSON with comments; preferred over TOML |
40
41## Common Mistakes
42
43| Mistake | Correct Pattern |
44| ----------------------------------------- | ------------------------------------------------------------- |
45| Accessing bindings as globals | Access via `env` parameter in module format |
46| Storing secrets in wrangler.toml | Use `wrangler secret put` for encrypted values |
47| Using KV for strong consistency | Use D1 or Durable Objects for consistent reads |
48| Not binding parameters in D1 queries | Always use `.prepare().bind()` to prevent SQL injection |
49| Exceeding KV value size (25 MiB) | Use R2 for objects larger than 25 MiB |
50| Forgetting `await` on storage operations | KV, D1, R2 methods are all async |
51| Using `fetch()` without passing `signal` | Pass `request.signal` for automatic cancellation |
52| Creating D1 database in Worker code | Create with `wrangler d1 create`, bind in config |
53| Missing `compatibility_date` in config | Always set to avoid breaking changes |
54| Returning non-Response from fetch handler | Must return a `Response` object |
55| Using `wrangler.toml` for new projects | Use `wrangler.jsonc` for new projects; has better IDE support |
56| Using KV for relational queries | Use D1 for SQL queries; KV is key-value only |
57
58## Delegation
59
60- **Architecture review**: Use `Task` agent to evaluate edge vs origin patterns
61- **Code review**: Delegate to `code-reviewer` agent
62- **Storage selection**: Use `Explore` agent to compare KV vs D1 vs R2 vs DO
63
64## References
65
66- [Workers syntax, fetch handler, scheduled events, and bindings](references/workers.md)
67- [KV, D1, R2, and Durable Objects storage APIs](references/storage.md)
68- [Cloudflare Pages, functions, routes, and build configuration](references/pages.md)
69- [Wrangler CLI, configuration, dev server, deploy, and secrets](references/wrangler.md)
oakoss