Workers Best Practices

Cloudflare Workers best practices for production applications. Use when writing, reviewing, or configuring Workers.

2 minutes · 512 words · 6 sections

Install

$ npx skills add cloudflare/skills --skill workers-best-practices

$ npx skills add cloudflare/skills

» /plugin marketplace add cloudflare/skills

The first command installs just this skill, by the name in its SKILL.md; the second installs the whole repository.

Your knowledge of Cloudflare Workers APIs, types, and configuration may be outdated. Prefer retrieval over pre-training when writing or reviewing Workers code.

Use the project’s installed versions, generated types, and Wrangler compatibility settings as the baseline for existing code. Retrieve relevant Cloudflare documentation to verify API, configuration, runtime behavior, and limit claims.

References

Workers Best Practices · cloudflare/skills · Skills Docs

Reference	When to use it
Configuration and observability (opens in a new tab)	Compatibility dates, bindings, generated types, secrets, logs, and traces
Runtime patterns (opens in a new tab)	Streaming, promise lifetime, request state, service calls, security, and runtime tests
Platform API checks (opens in a new tab)	Handler signatures, platform classes, binding access, and serialization

Anti-pattern	Consequence and preferred pattern
`await response.text()` or similar buffering on unbounded data	Can exhaust Worker memory; stream large or unbounded bodies (opens in a new tab).
Hardcoded secrets in source or config	Leaks credentials through version control; use Wrangler secrets.
`Math.random()` for security-sensitive tokens or IDs	Predictable values; use `crypto.randomUUID()` or `crypto.getRandomValues()`.
Async work started without awaiting, returning, or attaching it to `ctx.waitUntil()`	Work can be dropped and errors missed; tie it to the request or background-work lifetime.
Module-level mutable request state	Leaks data across requests and can cause I/O ownership errors; pass request state explicitly.
Cloudflare REST API calls for operations available through Worker bindings	Adds network and authentication overhead; use the available binding.
`ctx.passThroughOnException()` used as general error handling	Can conceal Worker failures by forwarding to the origin; use explicit error handling and structured error responses.
Hand-written `Env` that duplicates Wrangler bindings	Can drift from configuration; generate binding types with `wrangler types`.
Direct string comparison of secret values	Can expose timing differences; use the Web Crypto comparison pattern (opens in a new tab).
Destructuring `ctx` methods, such as `const { waitUntil } = ctx`	Loses the receiver; call `ctx.waitUntil(...)`.
`any` on `Env` or handler parameters	Hides binding and handler contract errors; use the project’s generated and platform types.
`as unknown as T` to force a platform type match	Hides incompatibilities; fix the underlying contract.
`implements` used in place of extending a platform base class	Does not inherit runtime behavior, `this.ctx`, or `this.env`; use the appropriate base class.
Unbound `env.X` in a platform class method	Bindings are available through `this.env.X`; see binding access patterns (opens in a new tab).
Applying one serialization rule across Queues, Workflow steps, storage, and WebSockets	Can reject valid payloads or accept unsupported ones; check the specific API and encoding (opens in a new tab).

Workers Best Practices

References

Workers Best Practices

References

Keep Compatibility Dates Current

Enable Observability

Anti-Patterns to Flag

Validation

Scope

Appendix 13.1–13.3

ReferencesMarkdown · 3 files

Colophon

Appendix 13.1–13.3

ReferencesMarkdown · 3 files