workers-code-review

✓ Official★ 4,910

by cloudflare · part of cloudflare/cloudflare-docs

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).

🧰 Not standalone. This skill ships with cloudflare/cloudflare-docs and only works together with that tool — install the tool first, then add this skill.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

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 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 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

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.