/workers-code-review

description: "Reviews Workers and Cloudflare Developer Platform code for type correctness, API usage, and configuration validity. Load when reviewing TypeScript/JavaScript using Workers APIs, wrangler.jsonc/toml config, or Cloudflare bindings (KV, R2, D1, Durable Objects, Queues, Vectorize, AI, Hyperdrive)."

Your knowledge of Cloudflare Workers APIs, types, and wrangler configuration may be outdated. **Prefer retrieval over pre-training** for any Workers code review task.

Reference Sources

Use the repo's local copies — do **not** run `npm pack` or install packages to fetch types.

| Source | Where to find it | Use for | | ---------------------- | ---------------------------------------------------------------- | ------------------------------------------------------ | | Wrangler config schema | `node_modules/wrangler/config-schema.json` | Config fields, binding shapes, allowed values | | Workers types | `node_modules/@cloudflare/workers-types/index.d.ts` | API usage, handler signatures, binding types | | Cloudflare docs search | Use the `cloudflare-docs` search tool or read files in this repo | API reference, compatibility dates/flags, binding docs |

Read these files directly when you need to verify a type, config field, or API signature. The guides in this folder describe what to validate — not how to fetch packages.

Review Process

1. Build Context

Read full files, not just diffs or isolated snippets. Code that looks wrong in isolation may be correct given surrounding logic.

• Identify the purpose of the code: is it a complete Worker, a snippet, a configuration example?
• Check git history for context: `git log --oneline -5 -- <file>`
• Understand which bindings, types, and patterns the code depends on

2. Categorize the Code

Every code block falls into one of three categories. Review **in the context** of its category.

| Category | Definition | Expectations | | ----------------- | -------------------------------------------------------------------- | ---------------------------------------------------- | | **Illustrative** | Demonstrates a concept; uses comments for most logic | Correct API names, realistic signatures | | **Demonstrative** | Functional but incomplete; would work if placed in the right context | Syntactically valid, correct APIs and binding access | | **Executable** | Standalone and complete; runs without modification | Compiles, runs, includes imports and config |

3. Validate with Tools

Run type-checking and linting. Tool output is evidence, not opinion.

npx tsc --noEmit                    # TypeScript errors
npx eslint <files>                  # Lint issues

For config files, validate against the latest wrangler config schema (see `wrangler-config.md` for retrieval) and check that all fields, binding types, and values conform.

4. Check Against Rules

See `workers-types.md` for type system rules, `wrangler-config.md` for config validation, and `common-patterns.md` for correct API patterns.

**Quick-reference rules:**

| Rule | Detail | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | Binding access | `env.X` in module export handlers; `this.env.X` in classes extending platform base classes. See `common-patterns.md`. | | No `any` | Never use `any` for binding types, handler params, or API responses. Use proper generics. | | No type-system cheats | Flag `as unknown as T`, unjustified `@ts-ignore`, unsafe assertions. See `workers-types.md`. | | Config-code consistency | Binding names in wrangler config must match `env.X` usage in code. See `wrangler-config.md`. | | Required config fields | Verify against the wrangler config schema — do not assume which fields are required. | | Concise examples | Examples should focus on core logic. Minimize boilerplate that distracts from what the code teaches. | | Floating promises | Every `Promise` must be `await`ed, `return`ed, `void`ed, or passed to `ctx.waitUntil()`. See `common-patterns.md`. | | Serialization | Data crossing Queue, Workflow step, or DO storage boundaries must be structured-clone serializable. See `common-patterns.md`. | | Streaming | Large/unknown payloads must stream, not buffer. Flag `await response.text()` on unbounded data. | | Error handling | Minimal but present — null checks on nullable returns, basic fetch error handling. Do not distract with verbose try/catch. |

5. Assess Risk

| Risk | Triggers | | ---------- | ---------------------------------------------------------------------------------------------------------- | | **HIGH** | Auth, crypto, external calls, value transfer, validation removal, access control, binding misconfiguration | | **MEDIUM** | Business logic, state changes, new public APIs, error handling, config changes | | **LOW** | Comments, logging, formatting, minor style |

Focus deeper analysis on HIGH risk. For critical paths, check blast radius: how many other files re