skilld
All skills
cloudflare avatar

/workers-best-practices

@41e0d19 official
by cloudflarecloudflare/skills3k stars
298

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

Ask your Agent

Use this Skill: https://skilld.dev/gh/cloudflare/skills/workers-best-practices

This session only. Nothing lands on disk.

referencesplatform-apis.md

≈969 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Workers Platform API Checks

Use the project's installed and generated types to check affected handlers and bindings. Consult current Cloudflare docs when API or runtime compatibility remains uncertain.

Type Validation

Env interface

  • Every binding must have a specific type. Flag any, unknown, object, or Record<string, unknown> on bindings.
  • Binding types that accept generic parameters (Durable Object namespaces, Queues, Service bindings for RPC) must include them. Read the type definition to confirm which types are generic.
  • Use the project's generated binding types; see configuration guidance.

Handler and class signatures

Verify affected signatures against the project's target type definitions; consult current docs if runtime support or compatibility remains uncertain.

  • Correct import path (most Workers platform classes import from "cloudflare:workers")
  • Generic type parameter on base classes (e.g., DurableObject<Env>)
  • ExecutionContext as the third param in module export handlers (needed for ctx.waitUntil())
  • fetch() handlers must return Promise<Response>

Binding access — the most common error

  • Module export handlers (fetch, scheduled, queue, email): bindings via env.X parameter
  • Platform base classes (WorkerEntrypoint, DurableObject, Workflow, Agent): bindings via this.env.X

Flag env.X inside a class extending a platform base class. Flag this.env.X inside a module export handler.

Stale class patterns

Old patterns survive in codebases long after APIs change.

  • extends vs implements: platform classes use extends, not implements. The implements pattern is legacy and loses this.ctx, this.env.
  • Import paths: verify module specifiers match what types actually export. Common mistake: wrong path for "cloudflare:workers" vs "cloudflare:workflows".
  • Renamed properties: e.g., this.state to this.ctx in Durable Objects. Search types to confirm.
  • Constructor signatures: base class constructors change. Verify expected parameters.

Serialization Boundaries

Check the API and encoding at each boundary. Structured clone support does not imply JSON compatibility or SQL parameter support.

Boundary What to check
Queue messages Match the body to contentType: json requires JSON-compatible data, text a string, bytes an ArrayBuffer, and v8 supports structured-clone values such as Map and Date. Check the configured compatibility date when relying on the default encoding.
Workflow step results Verify the step result against the documented serialization contract and the project's Workflow types before flagging a value.
Durable Object KV storage storage.put() supports structured-clone values; do not apply a blanket ban on Map or Set.
Durable Object SQL Check bound parameters against the SQL API's supported types. Encode objects explicitly for the intended column representation.
WebSocket messages Use send() with a string, ArrayBuffer, or ArrayBufferView; encode objects, for example with JSON.stringify().

Source: SKILL.md on GitHub

Third-party checks

1 warning16d5 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    This skill provides security and performance best practices for developing Cloudflare Workers. It contains no malicious patterns and actively encourages secure coding habits such as secret management and cryptographically secure random number generation.

  • Socket16d

    No alerts

  • Snyk16d

    Risk: LOW · No issues

  • Runlayer7mo

    3/3 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 41e0d19. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 6 hours ago.

Activeupdated 7 hours ago

Topics

  • Security
  • cloudflare
  • workers
  • best-practices
  • wrangler
  • observability
  • streaming
  • bindings
  • durable-objects
  • code-review

README badge

README badge for cloudflare/skills/workers-best-practices

What it does

Reviews and authors Cloudflare Workers code against production best practices, including streaming, floating promises, global state, secrets, bindings, and observability. Fetches latest Workers types and config schema rather than relying on pre-trained knowledge, making it suitable for code review and new Worker development in wrangler projects.

Generated from the current SKILL.md.

Frequently asked

Does this skill cover Durable Objects and Workflows?
No. This skill focuses on Workers-specific best practices. Load the separate durable-objects skill for Durable Objects guidance, and refer to the Rules of Workflows documentation for Workflows.
Should I use pre-trained knowledge or fetch fresh docs?
Always fetch fresh docs. The skill is designed to retrieve the latest Workers best practices page, types, and wrangler schema before writing or reviewing code, because APIs and config fields change frequently.
What anti-patterns does this skill flag?
Common patterns like unbounded `await response.text()` calls, hardcoded secrets, floating promises, module-level request state, destructuring ctx, and using the Cloudflare REST API from inside a Worker instead of in-process bindings.
Does this skill validate TypeScript types and config?
Yes. The skill checks binding types, handler signatures, wrangler.jsonc config fields, and will flag unsafe patterns like bare `any` types, double-casts, and hand-written Env interfaces that drift from actual bindings.
Can this skill help me set up observability and logging?
Yes. The skill covers enabling observability in wrangler config with head_sampling_rate and recommends structured JSON logging patterns for production Workers.

Generated from the current SKILL.md. These answers refresh after source changes.