workers-best-practices

Reviews and authors Cloudflare Workers code against production best practices and current type definitions.

3|1|Updated Apr 29, 2026
One-click install
npx skills add https://github.com/firstsun-dev/skills --skill workers-best-practices-firstsun-dev
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: workers-best-practices
Source: https://github.com/firstsun-dev/skills/tree/main/custom/develop/workers-best-practices
Command: npx skills add https://github.com/firstsun-dev/skills --skill workers-best-practices-firstsun-dev

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Cloudflare Workers APIs, types, and wrangler configuration change frequently, so code written from stale knowledge often contains wrong binding access patterns, outdated config fields, and anti-patterns like floating promises or buffered response bodies. This Skill grounds Workers authoring and review in retrieved, current references instead of outdated training data. ## Core Features & Use Cases - Best-Practice Rules: Applies canonical rules for streaming, waitUntil, bindings, secrets, observability, security, and testing when writing or refactoring Worker code. - Structured Code Review: Runs a retrieval-first review process covering type validation, wrangler config validation, serialization boundaries, and severity-ranked findings with file and line evidence. - Config Validation: Checks wrangler.jsonc for compatibility_date freshness, nodejs_compat, binding-code consistency, Durable Object migrations, and secrets stored in vars. - Use Case: When reviewing a pull request that adds a Queue producer to a Worker, the Skill fetches the latest @cloudflare/workers-types, verifies the Env binding types and handler signatures, and flags issues like any on bindings or non-serializable queue message bodies. ## Quick Start Ask the agent to review your Worker code and wrangler.jsonc against Cloudflare Workers best practices, fetching the latest types before flagging anything.

Frequently Asked Questions about workers-best-practices

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I review Cloudflare Workers code for best practices?▼

Fetch the latest @cloudflare/workers-types and wrangler config schema first, then check binding access patterns, handler signatures, config validity, and anti-patterns like floating promises. Report findings with severity levels and file/line evidence.

How do I access bindings in Cloudflare Workers correctly?▼

Module export handlers like fetch and scheduled access bindings via the env parameter as env.X. Classes extending platform base classes like WorkerEntrypoint or DurableObject use this.env.X instead. Mixing these patterns is the most common Workers error.

Should I use wrangler.toml or wrangler.jsonc for Workers config?▼

Prefer wrangler.jsonc for new projects because newer features are JSON-only and JSONC supports comments. wrangler.toml is legacy and should be flagged in new projects, though it remains acceptable in existing ones.

Why does my Worker crash on large response bodies?▼

Workers have a 128 MB memory limit, so buffering entire bodies with await response.text() crashes on large payloads. Stream data through using TransformStream or pass response.body directly into the new Response.

What causes floating promise errors in Cloudflare Workers?▼

A promise that is not awaited, returned, or passed to ctx.waitUntil() is floating, causing dropped results and swallowed errors. Enable the no-floating-promises lint rule and use ctx.waitUntil() for background work after the response.

When should I use Queues versus Workflows in Workers?▼

Use Queues for decoupled, single-step background jobs with at-least-once delivery and batching. Use Workflows for multi-step durable execution where each step's result is persisted and only failed steps retry, potentially running for hours or days.