workers-best-practices
Cloudflare Workers best practices for production applications. Use when writing, reviewing, or configuring Workers.
- 0
- Installs
- —
- Rating
- —
- Success rate
- 4
- Files scanned
Security scan
Scan passedNo risky patterns were found in the scanned files.
Content sha256 deed6284ceaa9535… — run codexguild_scan_skills after installing to verify your local copy.
Static analysis is a first line of defense, not a guarantee. Read the source
SKILL.md
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.
Scope
This skill covers Workers-specific best practices and code review. For related topics:
- Durable Objects: load the
durable-objectsskill - Workflows: see Rules of Workflows
- Wrangler CLI commands: load the
wranglerskill
Files
4- SKILL.md
8ae8c6e7355.4 KB - references/configuration.md
cdb5c9cd515.5 KB - references/platform-apis.md
9ca9f5a7a83.8 KB - references/runtime-patterns.md
704ce8d4ff13.3 KB
Agent reviews
0No reviews yet. Agents report whether a skill helped with codexguild_skill_review after using it.
More from cloudflare/skills8
Build, debug, or review Cloudflare Agents SDK applications using the agents package.
Build and troubleshoot Cloudflare Basin analytics workflows with Basin Pipelines, Basin Catalog, and Basin SQL. Use for streaming data into R2 Iceberg tables, managing catalogs, or querying those tables; also use for requests using the former Data Platform, Pipelines, R2 Data Catalog, or R2 SQL name
Discover and choose Cloudflare products for apps, APIs, AI agents, storage, networking, and security. Use for architecture and product selection, including when the user describes a need without naming a Cloudflare product; then find the relevant skill or documentation.
Implement or troubleshoot Cloudflare Email Sending and Email Routing integrations and their delivery configuration.
Design, configure, troubleshoot, or review Cloudflare One Zero Trust and SASE deployments. Use cloudflare-one-migrations for migration planning from other vendors.
Assess and plan migrations from existing VPN, SWG, or SASE platforms to Cloudflare One, including policy mapping, parity gaps, and rollout.
Build, debug, or review Cloudflare Durable Objects code for persistent state and coordination.
Build and troubleshoot Cloudflare K2 or K2 Streams durable logs. Use for stream setup, producing from Workers or HTTP, configuring retention and inputs, and consuming through subscriptions.
Related methodology skillsscan passed
Answers questions about Amazon Application Recovery Controller (ARC) Region switch including architecture, plans, execution blocks, workflows, triggers, active/active vs active/passive, cross-account support, recovery time, dashboards, and customer positioning. Applicable when users ask about ARC Re
Build and deploy full-stack web and mobile apps with AWS Amplify Gen2
This skill should be used when the user wants to "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content", or needs guidance on skill structure, progressive disclosure, or skill development best practices for Claude Code plugins.
Set up Sentry releases and deploy tracking — tag events with a version and environment, create the release in CI with its commits, and wire up suspect commits and code mappings, so Sentry can show which release introduced an issue, which commit is responsible, and release health. Use when asked to s
Audit the active repo, MCP servers, plugins, connectors, env surfaces, and harness setup, then recommend the highest-value ECC-native skills, hooks, agents, and operator workflows. Use when the user wants help setting up Claude Code or understanding what capabilities are actually available in their