Your knowledge of Cloudflare Workers APIs, types, and configuration may be outdated. Prefer retrieval over pre-training for any Workers code task — writing or reviewing.
Retrieval Sources
Fetch the latest versions before writing or reviewing Workers code. Do not rely on baked-in knowledge for API signatures, config fields, or binding shapes.
| Source |
How to retrieve |
Use for |
| Workers best practices |
Fetch https://developers.cloudflare.com/workers/best-practices/workers-best-practices/ |
Canonical rules, patterns, anti-patterns |
| Workers types |
See references/review.md for retrieval steps |
API signatures, handler types, binding types |
| Wrangler config schema |
node_modules/wrangler/config-schema.json |
Config fields, binding shapes, allowed values |
| Cloudflare docs |
Search tool or https://developers.cloudflare.com/workers/ |
API reference, compatibility dates/flags |
FIRST: Fetch Latest References
Before reviewing or writing Workers code, retrieve the current best practices page and relevant type definitions. If the project's node_modules has an older version, prefer the latest published version.
# Fetch latest workers types
mkdir -p /tmp/workers-types-latest && \
npm pack @cloudflare/workers-types --pack-destination /tmp/workers-types-latest && \
tar -xzf /tmp/workers-types-latest/cloudflare-workers-types-*.tgz -C /tmp/workers-types-latest
# Types at /tmp/workers-types-latest/package/index.d.ts
Reference Documentation
references/rules.md — all best practice rules with code examples and anti-patternsreferences/review.md — type validation, config validation, binding access patterns, review process
Rules Quick Reference
Configuration
| Rule |
Summary |
| Compatibility date |
Set compatibility_date to today on new projects; update periodically on existing ones |
| nodejs_compat |
Enable the nodejs_compat flag — many libraries depend on Node.js built-ins |
| wrangler types |
Run wrangler types to generate Env — never hand-write binding interfaces |
| Secrets |
Use wrangler secret put, never hardcode secrets in config or source |
| wrangler.jsonc |
Use JSONC config for non-secret settings — newer features are JSON-only |
Request & Response Handling
| Rule |
Summary |
| Streaming |
Stream large/unknown payloads — never await response.text() on unbounded data |
| waitUntil |
Use ctx.waitUntil() for post-response work; do not destructure ctx |
Architecture
| Rule |
Summary |
| Bindings over REST |
Use in-process bindings (KV, R2, D1, Queues) — not the Cloudflare REST API |
| Queues & Workflows |
Move async/background work off the critical path |
| Service bindings |
Use service bindings for Worker-to-Worker calls — not public HTTP |
| Hyperdrive |
Always use Hyperdrive for external PostgreSQL/MySQL connections |
Observability
| Rule |
Summary |
| Logs & Traces |
Enable observability in config with head_sampling_rate; use structured JSON logging |
Code Patterns
| Rule |
Summary |
| No global request state |
Never store request-scoped data in module-level variables |
| Floating promises |
Every Promise must be awaited, returned, voided, or passed to ctx.waitUntil() |
Security
| Rule |
Summary |
| Web Crypto |
Use crypto.randomUUID() / crypto.getRandomValues() — never Math.random() for security |
| No passThroughOnException |
Use explicit try/catch with structured error responses |
Anti-Patterns to Flag
| Anti-pattern |
Why it matters |
await response.text() on unbounded data |
Memory exhaustion — 128 MB limit |
| Hardcoded secrets in source or config |
Credential leak via version control |
Math.random() for tokens/IDs |
Predictable, not cryptographically secure |
Bare fetch() without await or waitUntil |
Floating promise — dropped result, swallowed error |
| Module-level mutable variables for request state |
Cross-request data leaks, stale state, I/O errors |
| Cloudflare REST API from inside a Worker |
Unnecessary network hop, auth overhead, added latency |
ctx.passThroughOnException() as error handling |
Hides bugs, makes debugging impossible |
Hand-written Env interface |
Drifts from actual wrangler config bindings |
| Direct string comparison for secret values |
Timing side-channel — use crypto.subtle.timingSafeEqual |
Destructuring ctx (const { waitUntil } = ctx) |
Loses this binding — throws "Illegal invocation" at runtime |
any on Env or handler params |
Defeats type safety for all binding access |
as unknown as T double-cast |
Hides real type incompatibilities — fix the design |
implements on platform base classes (instead of extends) |
Legacy — loses this.ctx, this.env. Applies to DurableObject, WorkerEntrypoint, Workflow |
env.X inside platform base class |
Should be this.env.X in classes extending DurableObject, WorkerEntrypoint, etc. |
Review Workflow
- Retrieve — fetch latest best practices page, workers types, and wrangler schema
- Read full files — not just diffs; context matters for binding access patterns
- Check types — binding access, handler signatures, no
any, no unsafe casts (see references/review.md)
- Check config — compatibility_date, nodejs_compat, observability, secrets, binding-code consistency
- Check patterns — streaming, floating promises, global state, serialization boundaries
- Check security — crypto usage, secret handling, timing-safe comparisons, error handling
- Validate with tools —
npx tsc --noEmit, lint for no-floating-promises
- Reference rules — see
references/rules.md for each rule's correct pattern
Scope
This skill covers Workers-specific best practices and code review. For related topics:
- Durable Objects: load the
durable-objects skill
- Workflows: see Rules of Workflows
- Wrangler CLI commands: load the
wrangler skill
Principles
- Be certain. Retrieve before flagging. If unsure about an API, config field, or pattern, fetch the docs first.
- Provide evidence. Reference line numbers, tool output, or docs links.
- Focus on what developers will copy. Workers code in examples and docs gets pasted into production.
- Correctness over completeness. A concise example that works beats a comprehensive one with errors.
1---2name: openai-cloudflare-workers-best-practices3description: Reviews and authors Cloudflare Workers code against production best practices. Load when writing new Workers, reviewing Worker code, configuring wrangler.jsonc, or checking for common Workers anti-patterns (streaming, floating promises, global state, secrets, bindings, observability). Biases towards retrieval from Cloudflare docs over pre-trained knowledge.4license: MIT5---6
7Your knowledge of Cloudflare Workers APIs, types, and configuration may be outdated. **Prefer retrieval over pre-training** for any Workers code task — writing or reviewing.
8
9## Retrieval Sources
10
11Fetch the **latest** versions before writing or reviewing Workers code. Do not rely on baked-in knowledge for API signatures, config fields, or binding shapes.
12
13| Source | How to retrieve | Use for |
14|--------|----------------|---------|
15| Workers best practices | Fetch `https://developers.cloudflare.com/workers/best-practices/workers-best-practices/` | Canonical rules, patterns, anti-patterns |
16| Workers types | See `references/review.md` for retrieval steps | API signatures, handler types, binding types |
17| Wrangler config schema | `node_modules/wrangler/config-schema.json` | Config fields, binding shapes, allowed values |
18| Cloudflare docs | Search tool or `https://developers.cloudflare.com/workers/` | API reference, compatibility dates/flags |
19
20## FIRST: Fetch Latest References
21
22Before reviewing or writing Workers code, retrieve the current best practices page and relevant type definitions. If the project's `node_modules` has an older version, **prefer the latest published version**.
23
24```bash
25# Fetch latest workers types
26mkdir -p /tmp/workers-types-latest && \
27 npm pack @cloudflare/workers-types --pack-destination /tmp/workers-types-latest && \
28 tar -xzf /tmp/workers-types-latest/cloudflare-workers-types-*.tgz -C /tmp/workers-types-latest
29# Types at /tmp/workers-types-latest/package/index.d.ts
30```
31
32## Reference Documentation
33
34- `references/rules.md` — all best practice rules with code examples and anti-patterns
35- `references/review.md` — type validation, config validation, binding access patterns, review process
36
37## Rules Quick Reference
38
39### Configuration
40
41| Rule | Summary |
42|------|---------|
43| Compatibility date | Set `compatibility_date` to today on new projects; update periodically on existing ones |
44| nodejs_compat | Enable the `nodejs_compat` flag — many libraries depend on Node.js built-ins |
45| wrangler types | Run `wrangler types` to generate `Env` — never hand-write binding interfaces |
46| Secrets | Use `wrangler secret put`, never hardcode secrets in config or source |
47| wrangler.jsonc | Use JSONC config for non-secret settings — newer features are JSON-only |
48
49### Request & Response Handling
50
51| Rule | Summary |
52|------|---------|
53| Streaming | Stream large/unknown payloads — never `await response.text()` on unbounded data |
54| waitUntil | Use `ctx.waitUntil()` for post-response work; do not destructure `ctx` |
55
56### Architecture
57
58| Rule | Summary |
59|------|---------|
60| Bindings over REST | Use in-process bindings (KV, R2, D1, Queues) — not the Cloudflare REST API |
61| Queues & Workflows | Move async/background work off the critical path |
62| Service bindings | Use service bindings for Worker-to-Worker calls — not public HTTP |
63| Hyperdrive | Always use Hyperdrive for external PostgreSQL/MySQL connections |
64
65### Observability
66
67| Rule | Summary |
68|------|---------|
69| Logs & Traces | Enable `observability` in config with `head_sampling_rate`; use structured JSON logging |
70
71### Code Patterns
72
73| Rule | Summary |
74|------|---------|
75| No global request state | Never store request-scoped data in module-level variables |
76| Floating promises | Every Promise must be `await`ed, `return`ed, `void`ed, or passed to `ctx.waitUntil()` |
77
78### Security
79
80| Rule | Summary |
81|------|---------|
82| Web Crypto | Use `crypto.randomUUID()` / `crypto.getRandomValues()` — never `Math.random()` for security |
83| No passThroughOnException | Use explicit try/catch with structured error responses |
84
85## Anti-Patterns to Flag
86
87| Anti-pattern | Why it matters |
88|-------------|----------------|
89| `await response.text()` on unbounded data | Memory exhaustion — 128 MB limit |
90| Hardcoded secrets in source or config | Credential leak via version control |
91| `Math.random()` for tokens/IDs | Predictable, not cryptographically secure |
92| Bare `fetch()` without `await` or `waitUntil` | Floating promise — dropped result, swallowed error |
93| Module-level mutable variables for request state | Cross-request data leaks, stale state, I/O errors |
94| Cloudflare REST API from inside a Worker | Unnecessary network hop, auth overhead, added latency |
95| `ctx.passThroughOnException()` as error handling | Hides bugs, makes debugging impossible |
96| Hand-written `Env` interface | Drifts from actual wrangler config bindings |
97| Direct string comparison for secret values | Timing side-channel — use `crypto.subtle.timingSafeEqual` |
98| Destructuring `ctx` (`const { waitUntil } = ctx`) | Loses `this` binding — throws "Illegal invocation" at runtime |
99| `any` on `Env` or handler params | Defeats type safety for all binding access |
100| `as unknown as T` double-cast | Hides real type incompatibilities — fix the design |
101| `implements` on platform base classes (instead of `extends`) | Legacy — loses `this.ctx`, `this.env`. Applies to DurableObject, WorkerEntrypoint, Workflow |
102| `env.X` inside platform base class | Should be `this.env.X` in classes extending DurableObject, WorkerEntrypoint, etc. |
103
104## Review Workflow
105
1061. **Retrieve** — fetch latest best practices page, workers types, and wrangler schema
1072. **Read full files** — not just diffs; context matters for binding access patterns
1083. **Check types** — binding access, handler signatures, no `any`, no unsafe casts (see `references/review.md`)
1094. **Check config** — compatibility_date, nodejs_compat, observability, secrets, binding-code consistency
1105. **Check patterns** — streaming, floating promises, global state, serialization boundaries
1116. **Check security** — crypto usage, secret handling, timing-safe comparisons, error handling
1127. **Validate with tools** — `npx tsc --noEmit`, lint for `no-floating-promises`
1138. **Reference rules** — see `references/rules.md` for each rule's correct pattern
114
115## Scope
116
117This skill covers Workers-specific best practices and code review. For related topics:
118
119- **Durable Objects**: load the `durable-objects` skill
120- **Workflows**: see [Rules of Workflows](https://developers.cloudflare.com/workflows/build/rules-of-workflows/)
121- **Wrangler CLI commands**: load the `wrangler` skill
122
123## Principles
124
125- **Be certain.** Retrieve before flagging. If unsure about an API, config field, or pattern, fetch the docs first.
126- **Provide evidence.** Reference line numbers, tool output, or docs links.
127- **Focus on what developers will copy.** Workers code in examples and docs gets pasted into production.
128- **Correctness over completeness.** A concise example that works beats a comprehensive one with errors.
yanacuti1121