workers-best-practices
Cloudflare Workers best practices for production applications. Use when writing, reviewing, or configuring Workers.
- Installs
- 559
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://developers.cloudflare.com --skill workers-best-practices- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads workers-best-practices automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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
- CLI commands: load the
cf-cliskill, or thewranglerskill in a project with a Wrangler configuration file
FAQ
What does the workers-best-practices skill do?
Cloudflare Workers best practices for production applications. Use when writing, reviewing, or configuring Workers.
How do I install workers-best-practices?
Run npx skills add https://developers.cloudflare.com --skill workers-best-practices in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/workers-best-practices/ (personal) or .claude/skills/workers-best-practices/ (project).
Which AI agents can use workers-best-practices?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is workers-best-practices safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains workers-best-practices?
It is published by developers.cloudflare.com in developers.cloudflare.com. It has 559 recorded installs.
More from developers.cloudflare.com
cloudflare
developers.cloudflare.com
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.
wrangler
developers.cloudflare.com
Run or troubleshoot Wrangler CLI commands in projects that have a wrangler.jsonc, wrangler.json, or wrangler.toml file, including local development, Previews, deployment, and resource management. For new projects and projects without a Wrangler configuration file, use the cf CLI instead.
durable-objects
developers.cloudflare.com
Open the skill to read its SKILL.md instructions.
agents-sdk
developers.cloudflare.com
Open the skill to read its SKILL.md instructions.
web-perf
developers.cloudflare.com
Open the skill to read its SKILL.md instructions.
sandbox-sdk
developers.cloudflare.com
Open the skill to read its SKILL.md instructions.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.