workers-best-practices

Check the project's wrangler.jsonc for current compatibility_date and nodejs_compat, verify bindings match generated types from wrangler types, and flag anti-patterns like buffered response bodies, floating promises, and hardcoded secrets. Consult current Cloudflare docs when API behavior is uncertain.

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

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.

Workers have a 128 MB memory limit, so buffering entire bodies with await response.text() or await response.arrayBuffer() crashes on large payloads. Stream data through with TransformStream or pass response.body directly to the new Response.

Use ctx.waitUntil() for background work like analytics, cache writes, or webhooks that should continue after the response is sent, with a 30-second post-response limit. Never destructure ctx, as it loses the this binding and throws Illegal invocation.

ctx.passThroughOnException() is a fail-open mechanism that forwards requests to the origin when the Worker throws, hiding bugs and complicating debugging. Use explicit try/catch blocks with structured JSON error responses and console.error logging instead.