AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

workers-best-practices

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

Original source
cloudflare
License
Apache-2.0
Pinned revision
e44f580f9c4fa3bf268e284ae7706c7954ba31fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read cloudflare--workers-best-practices at revision e44f580f9c4fa3bf268e284ae7706c7954ba31fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 5

references/platform-apis.md

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(). |