workers-best-practices

Fetch the latest Workers best practices page, workers types, and wrangler schema first, then read full files and check types, config, patterns, and security in order. Validate with npx tsc --noEmit and a no-floating-promises lint rule, and report findings with severity, file line references, and suggested fixes.

Key anti-patterns include awaiting response.text() on unbounded data, hardcoding secrets in wrangler vars, using Math.random() for tokens, floating promises without await or waitUntil, module-level mutable request state, and calling the Cloudflare REST API instead of using bindings.

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

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

Module export handlers like fetch and scheduled access bindings via the env parameter as env.X. Classes extending platform base classes such as DurableObject, WorkerEntrypoint, or Workflow must use this.env.X instead, and mixing these patterns is a common review finding.

Use Hyperdrive whenever a Worker connects to an external PostgreSQL or MySQL database, since it maintains a regional connection pool that eliminates per-request TCP, TLS, and auth overhead. Create a new Client per request using env.HYPERDRIVE.connectionString and enable the nodejs_compat flag.