Workers Best Practices
Retrieve current Cloudflare docs, installed Workers types, and the project's Wrangler schema before asserting an API signature or configuration rule.
Load references selectively:
- review.md for a structured Workers review and current type/config retrieval.
- rules.md for examples of specific runtime patterns.
Inspect the Workers boundary
Read the full affected entrypoint, binding types, Wrangler environment, and the callers of changed handlers. Check only Workers-specific risks supported by the code:
- binding names and generated types match the selected environment;
- secrets are not stored in source or ordinary
vars; - request-scoped mutable state does not leak through module globals;
- request and response bodies are streamed when their size is not safely bounded;
- every promise is awaited, returned, deliberately detached with
waitUntil, or explicitly discarded when safe; - platform base classes use their current inheritance and
this.envcontract; - Cloudflare services use bindings or service bindings when those are the intended application boundary; and
- cryptographic identifiers and secret comparisons use current Web Crypto APIs.
Do not flag a pattern merely because it differs from a preferred template. Confirm that it is incorrect for the installed types, compatibility date, and runtime path.
When serving static assets or an SPA, trace which requests reach the Worker
under the actual assets configuration. Worker middleware may not run for static
pages. Check that canonical-host/HTTPS redirects and required origin controls
cover the affected pages and APIs; choose routing or edge redirects deliberately
rather than defaulting every project to run_worker_first: true.
Review proportionally
- Retrieve only the docs and types relevant to the touched APIs.
- Verify Wrangler configuration and code agree.
- Trace serialization boundaries, body consumption, and background work.
- Run the narrow typecheck, test, lint, or local Worker exercise that can falsify the finding.
- Report concrete defects with file/line evidence and the smallest correction.
Route Durable Object design to durable-objects, exact CLI work to wrangler,
and material production rollout decisions to cloudflare-production-builder.
Do not turn a Workers code review into a general architecture or production
readiness program.
