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 reference guides in references/ 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 references/wrangler-config.md for retrieval) and check that all fields, binding types, and values conform.
4. Check Against Rules
See references/workers-types.md for type system rules, references/wrangler-config.md for config validation, and references/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 references/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 references/workers-types.md. |
| Config-code consistency |
Binding names in wrangler config must match env.X usage in code. See references/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 awaited, returned, voided, or passed to ctx.waitUntil(). See references/common-patterns.md. |
| Serialization |
Data crossing Queue, Workflow step, or DO storage boundaries must be structured-clone serializable. See references/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 reference this code?
Security logic escalation: for crypto, auth, and timing-sensitive code, do not stop at verifying API calls are correct. Examine the surrounding logic for flaws that undermine the security property (e.g., correct timingSafeEqual call but early return on length mismatch). See references/common-patterns.md Security section.
Anti-patterns to Flag
| Anti-pattern |
Why it matters |
any on Env or handler params |
Defeats type safety for every binding access downstream |
as unknown as T double-cast |
Hides real type incompatibilities — fix the underlying design |
@ts-ignore / @ts-expect-error without explanation |
Masks errors silently; require a comment justifying each suppression |
Buffering unbounded data (await res.text(), await res.json() on streams) |
Memory exhaustion on large payloads; use streaming |
| Hardcoded secrets or API keys |
Use env bindings and wrangler secret |
blockConcurrencyWhile on every request |
Only for initialization; blocks all concurrent requests |
| Single global Durable Object |
Creates a bottleneck; shard by coordination atom |
| In-memory-only state in DOs |
Lost on eviction; persist to SQLite storage |
| Missing DO migrations in config |
New DO classes require migration entries or deployment fails |
Floating promises (step.do(), fetch() without await) |
Silent bugs — drops results, breaks Workflow durability, ignores errors |
Non-serializable values across boundaries (Response, Error in step/queue) |
Compiles but fails at runtime; extract plain data before crossing boundary |
implements instead of extends on platform base classes |
Legacy pattern — loses this.ctx, this.env access from base class |
What NOT to Flag
- Style not enforced by linters
- "Could be cleaner" when code is correct and clear
- Theoretical performance concerns without evidence
- Missing features not in scope of the example
- Pre-existing issues in unchanged code
- TOML config in existing docs (only flag for new content)
Output Format
**[SEVERITY]** Brief description
`file.ts:42` — explanation with evidence (tool output, type error, config mismatch)
Suggested fix: `code` (if applicable)
Severity: CRITICAL (security, data loss, crash) | HIGH (type error, wrong API, broken config) | MEDIUM (missing validation, edge case, outdated pattern) | LOW (style, minor improvement)
End with a summary count by severity. If no issues found, say so directly.
Principles
- Be certain. Investigate before flagging. If you cannot confirm an API, binding pattern, or config field, retrieve the docs or schema first.
- Provide evidence. Reference line numbers, tool output, schema fields, or type definitions.
- Correctness over completeness. A concise example that works is better than a comprehensive one with errors.
- Respect existing patterns. Do not flag conventions already established in the codebase unless actively harmful.
- Focus on what developers will copy. Code in documentation gets pasted into production. Treat it accordingly.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: code-review-2323description: 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). Use when this capability is needed.4---56Your knowledge of Cloudflare Workers APIs, types, and wrangler configuration may be outdated. **Prefer retrieval over pre-training** for any Workers code review task.78## Reference Sources910Use the repo's local copies — do **not** run `npm pack` or install packages to fetch types.1112| Source | Where to find it | Use for |13| ---------------------- | ---------------------------------------------------------------- | ------------------------------------------------------ |14| Wrangler config schema | `node_modules/wrangler/config-schema.json` | Config fields, binding shapes, allowed values |15| Workers types | `node_modules/@cloudflare/workers-types/index.d.ts` | API usage, handler signatures, binding types |16| Cloudflare docs search | Use the `cloudflare-docs` search tool or read files in this repo | API reference, compatibility dates/flags, binding docs |1718Read these files directly when you need to verify a type, config field, or API signature. The reference guides in `references/` describe what to validate — not how to fetch packages.1920## Review Process2122### 1. Build Context2324Read full files, not just diffs or isolated snippets. Code that looks wrong in isolation may be correct given surrounding logic.2526- Identify the purpose of the code: is it a complete Worker, a snippet, a configuration example?27- Check git history for context: `git log --oneline -5 -- <file>`28- Understand which bindings, types, and patterns the code depends on2930### 2. Categorize the Code3132Every code block falls into one of three categories. Review **in the context** of its category.3334| Category | Definition | Expectations |35| ----------------- | -------------------------------------------------------------------- | ---------------------------------------------------- |36| **Illustrative** | Demonstrates a concept; uses comments for most logic | Correct API names, realistic signatures |37| **Demonstrative** | Functional but incomplete; would work if placed in the right context | Syntactically valid, correct APIs and binding access |38| **Executable** | Standalone and complete; runs without modification | Compiles, runs, includes imports and config |3940### 3. Validate with Tools4142Run type-checking and linting. Tool output is evidence, not opinion.4344```bash45npx tsc --noEmit # TypeScript errors46npx eslint <files> # Lint issues47```4849For config files, validate against the latest wrangler config schema (see `references/wrangler-config.md` for retrieval) and check that all fields, binding types, and values conform.5051### 4. Check Against Rules5253See `references/workers-types.md` for type system rules, `references/wrangler-config.md` for config validation, and `references/common-patterns.md` for correct API patterns.5455**Quick-reference rules:**5657| Rule | Detail |58| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |59| Binding access | `env.X` in module export handlers; `this.env.X` in classes extending platform base classes. See `references/common-patterns.md`. |60| No `any` | Never use `any` for binding types, handler params, or API responses. Use proper generics. |61| No type-system cheats | Flag `as unknown as T`, unjustified `@ts-ignore`, unsafe assertions. See `references/workers-types.md`. |62| Config-code consistency | Binding names in wrangler config must match `env.X` usage in code. See `references/wrangler-config.md`. |63| Required config fields | Verify against the wrangler config schema — do not assume which fields are required. |64| Concise examples | Examples should focus on core logic. Minimize boilerplate that distracts from what the code teaches. |65| Floating promises | Every `Promise` must be `await`ed, `return`ed, `void`ed, or passed to `ctx.waitUntil()`. See `references/common-patterns.md`. |66| Serialization | Data crossing Queue, Workflow step, or DO storage boundaries must be structured-clone serializable. See `references/common-patterns.md`. |67| Streaming | Large/unknown payloads must stream, not buffer. Flag `await response.text()` on unbounded data. |68| Error handling | Minimal but present — null checks on nullable returns, basic fetch error handling. Do not distract with verbose try/catch. |6970### 5. Assess Risk7172| Risk | Triggers |73| ---------- | ---------------------------------------------------------------------------------------------------------- |74| **HIGH** | Auth, crypto, external calls, value transfer, validation removal, access control, binding misconfiguration |75| **MEDIUM** | Business logic, state changes, new public APIs, error handling, config changes |76| **LOW** | Comments, logging, formatting, minor style |7778Focus deeper analysis on HIGH risk. For critical paths, check blast radius: how many other files reference this code?7980**Security logic escalation**: for crypto, auth, and timing-sensitive code, do not stop at verifying API calls are correct. Examine the surrounding logic for flaws that undermine the security property (e.g., correct `timingSafeEqual` call but early return on length mismatch). See `references/common-patterns.md` Security section.8182## Anti-patterns to Flag8384| Anti-pattern | Why it matters |85| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------- |86| `any` on `Env` or handler params | Defeats type safety for every binding access downstream |87| `as unknown as T` double-cast | Hides real type incompatibilities — fix the underlying design |88| `@ts-ignore` / `@ts-expect-error` without explanation | Masks errors silently; require a comment justifying each suppression |89| Buffering unbounded data (`await res.text()`, `await res.json()` on streams) | Memory exhaustion on large payloads; use streaming |90| Hardcoded secrets or API keys | Use `env` bindings and `wrangler secret` |91| `blockConcurrencyWhile` on every request | Only for initialization; blocks all concurrent requests |92| Single global Durable Object | Creates a bottleneck; shard by coordination atom |93| In-memory-only state in DOs | Lost on eviction; persist to SQLite storage |94| Missing DO migrations in config | New DO classes require migration entries or deployment fails |95| Floating promises (`step.do()`, `fetch()` without `await`) | Silent bugs — drops results, breaks Workflow durability, ignores errors |96| Non-serializable values across boundaries (`Response`, `Error` in step/queue) | Compiles but fails at runtime; extract plain data before crossing boundary |97| `implements` instead of `extends` on platform base classes | Legacy pattern — loses `this.ctx`, `this.env` access from base class |9899## What NOT to Flag100101- Style not enforced by linters102- "Could be cleaner" when code is correct and clear103- Theoretical performance concerns without evidence104- Missing features not in scope of the example105- Pre-existing issues in unchanged code106- TOML config in existing docs (only flag for new content)107108## Output Format109110```111**[SEVERITY]** Brief description112`file.ts:42` — explanation with evidence (tool output, type error, config mismatch)113Suggested fix: `code` (if applicable)114```115116Severity: **CRITICAL** (security, data loss, crash) | **HIGH** (type error, wrong API, broken config) | **MEDIUM** (missing validation, edge case, outdated pattern) | **LOW** (style, minor improvement)117118End with a summary count by severity. If no issues found, say so directly.119120## Principles121122- **Be certain.** Investigate before flagging. If you cannot confirm an API, binding pattern, or config field, retrieve the docs or schema first.123- **Provide evidence.** Reference line numbers, tool output, schema fields, or type definitions.124- **Correctness over completeness.** A concise example that works is better than a comprehensive one with errors.125- **Respect existing patterns.** Do not flag conventions already established in the codebase unless actively harmful.126- **Focus on what developers will copy.** Code in documentation gets pasted into production. Treat it accordingly.127128---129> Converted and distributed by [TomeVault](https://tomevault.io/claim/cloudflare) — claim your Tome and manage your conversions.130<!-- tomevault:4.0:skill_md:2026-04-11 -->
tomevault-io