Your baked-in knowledge of Workers APIs, config fields, and binding shapes is stale. Retrieve first: every API signature, config field, and binding shape you assert comes from a source fetched this session, and a finding you cannot cite a source for does not get reported.
1. Retrieve
Fetch before writing or reviewing a single line. Prefer the latest published version over whatever node_modules pins.
# Latest workers types → /tmp/workers-types-latest/package/index.d.ts
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
| Source | Where | Use for |
|---|---|---|
| Best practices page | https://developers.cloudflare.com/workers/best-practices/workers-best-practices/ |
Canonical rules and anti-patterns |
| Workers types | the npm pack above |
API signatures, handler types, binding types |
| Wrangler config schema | node_modules/wrangler/config-schema.json |
Config fields, binding shapes, allowed values |
| Cloudflare docs | search, or https://developers.cloudflare.com/workers/ |
API reference, compatibility dates and flags |
Done when the types, the config schema, and the best practices page are all in context.
2. Apply the rules
references/rules.md is the single source of truth for every rule — configuration, request handling, architecture, observability, code patterns, security, testing — each with its correct pattern and the anti-pattern it replaces. Read it, then work the rule set:
- Authoring — every rule in the relevant sections holds in the code you write.
- Reviewing — read the full files rather than the diff, since binding access and global state only read correctly in context, then check every rule against them.
Done when every rule in references/rules.md has been applied or consciously judged inapplicable — not when the obvious ones pass.
3. Verify and report
Run npx tsc --noEmit and lint for no-floating-promises; a rule a tool can check is checked by the tool, not by eye.
For a review, references/review.md carries the review-specific reference: type and config validation, serialization boundaries, how to grade illustrative vs executable code, risk levels, and the finding format. Read it before writing up findings.
Done when every finding names a file and line, cites its evidence, and carries a severity.
Anti-patterns to flag
The recurring ones, as a scan list — each is explained in full in references/rules.md.
| 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 or 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 | Extra network hop, auth overhead, added latency |
ctx.passThroughOnException() as error handling |
Hides bugs and makes debugging impossible |
Hand-written Env interface |
Drifts from the actual wrangler config bindings |
| Direct string comparison of secrets | Timing side-channel — use crypto.subtle.timingSafeEqual |
Destructuring ctx (const { waitUntil } = ctx) |
Loses this binding — "Illegal invocation" at runtime |
any on Env or handler params |
Defeats type safety for every binding access |
as unknown as T double-cast |
Hides a real type incompatibility — fix the design |
implements on a platform base class |
Legacy — loses this.ctx and this.env; use extends on DurableObject, WorkerEntrypoint, Workflow |
env.X inside a platform base class |
Should be this.env.X |
Scope
Workers themselves. For the wider platform — Durable Objects, Workflows, Wrangler commands, KV/D1/R2 — load the cloudflare umbrella skill, whose references/ carries a file per product.