sb-dev/openquant / .agents/skills/workers-best-practices
workers-best-practices
VerifiedCloudflare Workers best practices for production applications. Use when writing, reviewing, or configuring Workers.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.1 KB |
| references/configuration.md | markdown | 6.6 KB |
| references/platform-apis.md | markdown | 3.8 KB |
| references/runtime-patterns.md | markdown | 13.5 KB |
| references/skill-feedback.md | markdown | 2.8 KB |
references/platform-apis.md
View on GitHub# 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](#type-validation): binding types, handler signatures, and platform classes
- [Serialization boundaries](#serialization-boundaries): encoding and supported values for each API
## 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](configuration.md#generate-binding-types-with-wrangler-types).
### 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](https://developers.cloudflare.com/queues/configuration/javascript-apis/index.md#queuescontenttype) | 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](https://developers.cloudflare.com/workflows/build/workers-api/index.md) | Verify the step result against the documented serialization contract and the project's Workflow types before flagging a value. |
| [Durable Object KV storage](https://developers.cloudflare.com/durable-objects/api/sqlite-storage-api/index.md#do-kv-async-put) | `storage.put()` supports structured-clone values; do not apply a blanket ban on `Map` or `Set`. |
| [Durable Object SQL](https://developers.cloudflare.com/durable-objects/api/sqlite-storage-api/index.md#exec) | Check bound parameters against the SQL API's supported types. Encode objects explicitly for the intended column representation. |
| [WebSocket messages](https://developers.cloudflare.com/workers/runtime-apis/websockets/index.md#send) | Use `send()` with a string, `ArrayBuffer`, or `ArrayBufferView`; encode objects, for example with `JSON.stringify()`. |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |