workers-best-practices

Follow the eight-step review workflow: retrieve the latest workers types and wrangler schema, read full files, check types and binding access, validate config, check patterns like streaming and floating promises, verify security, and run tsc and lint checks. Findings are reported with severity, file, and line evidence.

Key anti-patterns include awaiting response.text() on unbounded data, hardcoded secrets in config, Math.random() for tokens, floating promises without await or waitUntil, module-level mutable request state, calling the Cloudflare REST API from inside a Worker, and destructuring ctx which loses the this binding.

Use wrangler.jsonc for new projects because newer Cloudflare features are JSON-only and JSONC supports comments for documenting config decisions. wrangler.toml is legacy and acceptable in existing projects but should be flagged in new ones.

In module export handlers like fetch, access bindings via the env parameter (env.X). In classes extending platform base classes like DurableObject, WorkerEntrypoint, or Workflow, use this.env.X. Mixing these patterns is the most common binding error.

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

Always use Hyperdrive for external PostgreSQL or MySQL connections from a Worker. It maintains a regional connection pool that eliminates per-request TCP, TLS, and auth overhead of 300-500ms, and requires the nodejs_compat compatibility flag.