workers-best-practices

$2a

# Fetch latest workers types

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

# Types at /tmp/workers-types-latest/package/index.d.ts

Reference Documentation

• references/rules.md — all best practice rules with code examples and anti-patterns

• references/review.md — type validation, config validation, binding access patterns, review process

Rules Quick Reference

Configuration

Rule

Summary

Compatibility date

Set compatibility_date to today on new projects; update periodically on existing ones

nodejs_compat

Enable the nodejs_compat flag — many libraries depend on Node.js built-ins

wrangler types

Run wrangler types to generate Env — never hand-write binding interfaces

Secrets

Use wrangler secret put, never hardcode secrets in config or source

wrangler.jsonc

Use JSONC config for non-secret settings — newer features are JSON-only

Request & Response Handling

Rule

Summary

Streaming

Stream large/unknown payloads — never await response.text() on unbounded data

waitUntil

Use ctx.waitUntil() for post-response work; do not destructure ctx

Architecture

Rule

Summary

Bindings over REST

Use in-process bindings (KV, R2, D1, Queues) — not the Cloudflare REST API

Queues & Workflows

Move async/background work off the critical path

Service bindings

Use service bindings for Worker-to-Worker calls — not public HTTP

Hyperdrive

Always use Hyperdrive for external PostgreSQL/MySQL connections

Observability

Rule

Summary

Logs & Traces

Enable observability in config with head_sampling_rate; use structured JSON logging

Code Patterns

Rule

Summary

No global request state

Never store request-scoped data in module-level variables

Floating promises

Every Promise must be awaited, returned, voided, or passed to ctx.waitUntil()

Security

Rule

Summary

Web Crypto

Use crypto.randomUUID() / crypto.getRandomValues() — never Math.random() for security

No passThroughOnException

Use explicit try/catch with structured error responses

Anti-Patterns to Flag

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

Unnecessary network hop, auth overhead, added latency

ctx.passThroughOnException() as error handling

Hides bugs, makes debugging impossible

Hand-written Env interface

Drifts from actual wrangler config bindings

Direct string comparison for secret values

Timing side-channel — use crypto.subtle.timingSafeEqual

Destructuring ctx (const { waitUntil } = ctx)

Loses this binding — throws "Illegal invocation" at runtime

any on Env or handler params

Defeats type safety for all binding access

as unknown as T double-cast

Hides real type incompatibilities — fix the design

implements on platform base classes (instead of extends)

Legacy — loses this.ctx, this.env. Applies to DurableObject, WorkerEntrypoint, Workflow

env.X inside platform base class

Should be this.env.X in classes extending DurableObject, WorkerEntrypoint, etc.

Review Workflow

• Retrieve — fetch latest best practices page, workers types, and wrangler schema

• Read full files — not just diffs; context matters for binding access patterns

• Check types — binding access, handler signatures, no any, no unsafe casts (see references/review.md)

• Check config — compatibility_date, nodejs_compat, observability, secrets, binding-code consistency

• Check patterns — streaming, floating promises, global state, serialization boundaries

• Check security — crypto usage, secret handling, timing-safe comparisons, error handling

• Validate with tools — npx tsc --noEmit, lint for no-floating-promises

• Reference rules — see references/rules.md for each rule's correct pattern

Scope

This skill covers Workers-specific best practices and code review. For related topics:

• Durable Objects: load the durable-objects skill

• Workflows: see Rules of Workflows

• Wrangler CLI commands: load the wrangler skill

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.