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 findings with npx tsc --noEmit and a no-floating-promises lint rule, and report issues with severity levels and suggested fixes.

Key anti-patterns include awaiting response.text() on unbounded data, hardcoded secrets, 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. TOML is legacy and acceptable in existing projects but should be flagged in new ones.

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

Destructuring ctx, such as const { waitUntil } = ctx, loses the this binding that waitUntil depends on, throwing Illegal invocation at runtime. Always call ctx.waitUntil() directly on the context object.

Use Hyperdrive whenever a Worker connects to an external PostgreSQL or MySQL database. It maintains a regional connection pool that eliminates per-request TCP, TLS, and auth overhead, and requires the nodejs_compat compatibility flag.