workers-best-practices

Check the project's wrangler config, generated types, and compatibility settings as the baseline, then verify API and runtime claims against current Cloudflare documentation. Flag anti-patterns like buffering unbounded bodies, hardcoded secrets, and floating promises.

Common anti-patterns include awaiting response.text() on unbounded data, using Math.random() for security tokens, storing request state in module scope, calling Cloudflare REST APIs instead of bindings, and destructuring ctx which loses the this binding.

Set observability.enabled and observability.traces.enabled to true in wrangler.jsonc; the top-level setting alone does not enable traces. Use structured JSON logging via console.log(JSON.stringify(...)) and configure head_sampling_rate for volume control.

Prefer wrangler.jsonc over wrangler.toml because newer features are JSON-only and JSONC supports comments for documenting configuration decisions. Flag wrangler.toml in new projects.

This error typically comes from mutable module-level state shared across requests, since Workers reuse isolates. Pass request state explicitly through function arguments instead of assigning to module-scope variables inside handlers.

Use Queues for decoupled, single-step background jobs with at-least-once delivery and batching. Use Workflows for multi-step durable execution where each step's result is persisted and only failed steps retry, even over hours or days.