Workers Best Practices

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.

When to Use

Load this skill when:

• Writing new Cloudflare Workers code or scaffolding a new Worker project
• Reviewing existing Worker code in a PR, audit, or refactor
• Configuring wrangler.jsonc / wrangler.toml — bindings, compatibility flags, observability
• Diagnosing common Workers anti-patterns: floating promises, global mutable state, unbounded await response.text(), hardcoded secrets, REST API calls from inside a Worker
• Checking binding access patterns in platform base classes (DurableObject, WorkerEntrypoint, Workflow)

Do not load this skill for:

• Durable Objects specifics — load the durable-objects skill instead
• Wrangler CLI command reference — load the wrangler skill
• Workflows rules — see Rules of Workflows

Prerequisites

• Node.js and npm installed on the host
• wrangler available locally (node_modules/.bin/wrangler) or globally
• PowerShell as the primary shell on Windows host
• Internet access for fetching Cloudflare docs and npm pack

Procedure

Step 1 — Fetch Latest References Before Writing or Reviewing

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 the canonical best practices page:

# Fetch the Workers best practices page
Invoke-WebRequest -Uri "https://developers.cloudflare.com/workers/best-practices/workers-best-practices/" -OutFile "$env:TEMP\workers-best-practices.html"

Fetch the latest @cloudflare/workers-types package:

# Create temp dir and fetch latest workers types
New-Item -ItemType Directory -Force -Path "$env:TEMP\workers-types-latest"
npm pack @cloudflare/workers-types --pack-destination "$env:TEMP\workers-types-latest"
# Extract the tarball
$tarball = Get-ChildItem "$env:TEMP\workers-types-latest\cloudflare-workers-types-*.tgz" | Select-Object -First 1
tar -xzf $tarball.FullName -C "$env:TEMP\workers-types-latest"
# Types at $env:TEMP\workers-types-latest\package\index.d.ts

Check the local wrangler config schema:

# If wrangler is installed locally, the schema is available at:
# node_modules\wrangler\config-schema.json
# Use it to validate config fields, binding shapes, and allowed values
Test-Path "node_modules\wrangler\config-schema.json"

Step 2 — Load Reference Files

Load these reference files at the right time during review:

Step 3 — Retrieve Latest Docs for Any Uncertain API

If unsure about an API signature, config field, or binding shape, fetch the docs first:

# Search Cloudflare Workers docs
Invoke-WebRequest -Uri "https://developers.cloudflare.com/workers/" -UseBasicParsing

Step 4 — Review Workflow

Follow this ordered process for every Workers code review:

1. Retrieve — fetch latest best practices page, workers types, and wrangler schema (Step 1 above)
2. Read full files — not just diffs; context matters for binding access patterns
3. Check types — binding access, handler signatures, no any, no unsafe casts (see references/review.md)
4. Check config — compatibility_date, nodejs_compat, observability, secrets, binding-code consistency
5. Check patterns — streaming, floating promises, global state, serialization boundaries
6. Check security — crypto usage, secret handling, timing-safe comparisons, error handling
7. Validate with tools — npx tsc --noEmit, lint for no-floating-promises
8. Reference rules — see references/rules.md for each rule's correct pattern

Step 5 — Apply Configuration Rules

Step 6 — Apply Request & Response Handling Rules

Step 7 — Apply Architecture Rules

Step 8 — Apply Observability Rules

Step 9 — Apply Code Pattern Rules

Step 10 — Apply Security Rules

Pitfalls

Anti-Patterns to Flag

Hard Rules

• Never hardcode secrets in source or config — always use wrangler secret put
• Never use Math.random() for security-sensitive tokens or IDs
• Never store request-scoped data in module-level mutable variables
• Never destructure ctx — always call ctx.waitUntil() directly
• Never hand-write the Env interface — run wrangler types to generate it
• Never use any on Env or handler parameters
• Never use as unknown as T double-cast — fix the underlying type incompatibility
• Never use implements on platform base classes — use extends instead
• Never access env.X inside a platform base class — use this.env.X
• Never use ctx.passThroughOnException() as error handling — use explicit try/catch
• Never call the Cloudflare REST API from inside a Worker — use in-process bindings
• Never await response.text() on unbounded data — stream instead

Verification

Type Check

npx tsc --noEmit

Expected: zero errors. If errors appear, check binding access patterns and handler signatures against references/review.md.

Lint for Floating Promises

# If using TypeScript ESLint with strict config
npx eslint . --rule '{"no-floating-promises": "error"}'

Expected: zero no-floating-promises violations.

Generate Types from Wrangler Config

npx wrangler types

Expected: generates worker-configuration.d.ts (or project-configured output). Verify the generated Env interface matches bindings declared in wrangler.jsonc.

Check Config for Required Fields

# Verify wrangler.jsonc has compatibility_date, nodejs_compat, and observability
Get-Content "wrangler.jsonc" | Select-String -Pattern "compatibility_date|nodejs_compat|observability|head_sampling_rate"

Expected: all four patterns found in the config file.

Check for Hardcoded Secrets

# Search for common secret patterns in source (excluding node_modules)
Get-ChildItem -Recurse -Include "*.ts","*.js","*.jsonc","*.toml" -Exclude "node_modules" | Select-String -Pattern "(?i)(api_key|secret|token|password)\s*[:=]\s*['\""][^'\""]{8,}" | Where-Object { $_.Path -notmatch "node_modules" }

Expected: zero matches (or only placeholder values like YOUR_KEY).

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.

Related Skills

• Durable Objects: load the durable-objects skill for DO-specific patterns
• Workflows: see Rules of Workflows
• Wrangler CLI commands: load the wrangler skill