workers-best-practices

Fetch the latest Workers best practices page, workers types, and wrangler schema first, then check types, config, patterns, and security in order. Validate with npx tsc --noEmit and lint for no-floating-promises, and report findings with severity levels and suggested fixes.

Key anti-patterns include awaiting response.text() on unbounded data, hardcoded secrets, Math.random() for tokens, floating promises, module-level request state, and calling the Cloudflare REST API from inside a Worker instead of using bindings.

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

Classes extending platform base classes like DurableObject, WorkerEntrypoint, and Workflow access bindings via this.env.X, while module export handlers use the env.X parameter. Mixing these patterns is the most common binding access error.

Destructuring ctx with const { waitUntil } = ctx loses the this binding, causing an Illegal invocation error at runtime. Always call ctx.waitUntil() directly on the ExecutionContext object.

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, and it requires the nodejs_compat flag.