workers-best-practices

작성자: Cloudflare

Cloudflare Workers 코드를 프로덕션 모범 사례에 따라 검토하고 작성합니다. 새 Workers를 작성하거나, Worker 코드를 검토하거나, wrangler.jsonc를 구성하거나, 일반적인 Workers 안티 패턴(스트리밍, 플로팅 프로미스, 전역 상태, 시크릿, 바인딩, 관찰 가능성)을 확인할 때 로드합니다. 사전 학습된 지식보다 Cloudflare 문서에서 검색하는 것을 선호합니다.

npx skills add https://github.com/cloudflare/skills --skill workers-best-practices

ZIP 다운로드 GitHub

2.9k

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

Read the sections relevant to the task:

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

For missing evidence, consult Workers best practices or find the affected product in the Cloudflare docs directory. Use the installed Wrangler schema for config fields. A newer type package does not supersede the project's configured target.

Keep Compatibility Dates Current

Use today's date for new Workers. Encourage periodic updates for existing Workers, reviewing compatibility changes and running relevant tests. Assess existing behavior against its configured date and flags; see compatibility guidance.

Enable Observability

Enable Workers Logs and Traces when creating or preparing a Worker for production. Set observability.enabled and observability.traces.enabled to true; the top-level setting alone does not enable traces. Use structured JSON logging and configure sampling for the workload. During reviews, flag missing logs or traces. See the configuration example.

Anti-Patterns to Flag

Anti-pattern	Consequence and preferred pattern
`await response.text()` or similar buffering on unbounded data	Can exhaust Worker memory; stream large or unbounded bodies.
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.
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.
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.

Validation

Use the project's existing checks for affected Workers behavior: type-check binding or handler contract changes, and run relevant runtime tests for behavior changes. Preserve required repository checks; a narrow edit does not require a full Workers audit.