Cloudflare Workers Author

Companion rule: 401-cloudflare-workers.mdc (file-scoped to wrangler.{jsonc,toml,json} and common Worker entry-point names). The rule is the gate (non-negotiables); this skill is the workflow (how to actually build the Worker).

Voice: opinionated. Cloudflare Workers is a small, fast platform with a specific runtime model. Most production incidents come from treating it like a generic Node.js server (top-level await, mutable module state, unbounded loops, secrets in logs, public-URL Worker-to-Worker calls). The workflow below prevents those.

When to invoke this skill

Invoke when:

• The user asks to build a new Cloudflare Worker, Durable Object, Workflow, Queue consumer, Cron Trigger, Email Worker, or Pages Function.
• The user is adding routes / endpoints to an existing Worker.
• The user asks "should I use KV / D1 / R2 / DO / Hyperdrive for this?" (the bindings-and-storage decision matrix is the answer).
• The user is setting up testing for a Worker.
• The user is configuring deployment (gradual rollouts, OIDC for GitHub Actions, secret rotation).
• A PR review touches wrangler.jsonc, a Worker entry-point file, or a binding configuration.

Do NOT invoke for:

• Cloudflare Pages static-site work (not Worker authoring). See cloud-platforms/references/cloudflare.md § Pages.
• WAF rule authoring (use cloudflare-waf-author skill instead).
• Generic JavaScript / TypeScript code that happens to be imported by a Worker - delegate to the typescript-javascript skill.

Pre-step: classify what you're building

Each Worker type has a different entry-point shape and different bindings emphasis. Ask the user which one if unclear - the wrong entry-point shape is a wrong-handler-signature bug that won't surface until deploy time.

The six-step workflow

Step 1 - Bootstrap the project

If this is a new Worker (no existing wrangler.jsonc), follow references/project-bootstrap.md to get a minimal Module Workers project with:

• wrangler.jsonc (the modern config format - JSONC with comments; recommended by Cloudflare since Wrangler v3.91.0)
• package.json with wrangler, typescript, and a types script that runs wrangler types
• tsconfig.json with strict mode, ESNext target, "types": [], and the generated worker-configuration.d.ts in include
• src/worker.ts with the generated Env type (do not hand-author it) and satisfies ExportedHandler<Env>
• .dev.vars in .gitignore; worker-configuration.d.ts generated by wrangler types

[!IMPORTANT] wrangler types now generates the Workers runtime types and supersedes @cloudflare/workers-types. Current Wrangler (4.9x+) prints this on every wrangler types run and tells you to uninstall @cloudflare/workers-types and remove it from tsconfig.json. The generated worker-configuration.d.ts provides both the global Env (from vars + declared secrets) and the runtime globals (Request, Response, ExecutionContext, ExportedHandler, etc.), pinned to your compatibility_date. So: no @cloudflare/workers-types dependency, "types": [] in tsconfig.json, and worker-configuration.d.ts in include. Declare expected secrets under secrets.required in wrangler.jsonc so they appear in the generated Env. Vars are typed as their literal values by default; run wrangler types --strict-vars=false to type them as string when a var's value varies by environment.

If the user already has a Worker, read their existing wrangler.jsonc before suggesting changes. Don't propose a fresh structure that conflicts with their conventions.

Step 2 - Choose bindings and storage

This is the most consequential design decision in any new Worker. Pick wrong and you'll be migrating data in six months. The full decision matrix is in references/bindings-and-storage.md; the headline:

Document the choice in the PR description with the rejected alternatives and why.

Step 3 - Route requests

Pick a router based on complexity:

For Hono patterns (typed env via Hono<{ Bindings: Env, Variables: ... }>, middleware, error boundaries, OpenAPI) and RPC patterns (when to use, named entrypoints, lifecycle), see references/hono-patterns.md.

Step 4 - Test

The canonical testing path is @cloudflare/vitest-plugin v1+ with Vitest 4.1+. It runs tests inside the Workers runtime via Miniflare, with bindings mocked or real (your choice), HMR for fast reruns, and isolated per-test storage.

See references/testing-with-vitest-pool.md for setup details. The pattern:

• vitest.config.ts registers the cloudflareTest() Vite plugin (exported from @cloudflare/vitest-plugin) inside a standard defineConfig from vitest/config, pointing at your wrangler.jsonc
• tsconfig.json for tests includes "@cloudflare/vitest-plugin/types" in types (declares the cloudflare:test module)
• Unit tests: import the handler, call worker.fetch(request, env, ctx) directly with mocked env
• Integration tests: use SELF.fetch() from cloudflare:test (in-process) or auxiliary Workers (fresh isolate)

[!IMPORTANT] Cloudflare renamed @cloudflare/vitest-pool-workers to @cloudflare/vitest-plugin in v1. Migrate the dependency, package imports, and TypeScript types entry. The configuration API remains cloudflareTest({ wrangler: { configPath: "./wrangler.jsonc" } }) inside plugins in a vitest/config defineConfig; do not restore the removed defineWorkersConfig helper.

Reject in review: new tests using unstable_dev or the renamed @cloudflare/vitest-pool-workers package.

Step 5 - Deploy and roll out gradually

Workers supports two deployment models:

• Standard deploy (wrangler deploy) - upload and immediately serve 100% from the new version. Fine for low-risk changes.
• Gradual deployment (wrangler versions upload then wrangler versions deploy) - upload as a new version without serving traffic, split traffic between old and new, then promote to 100%. Required for production HTTP Workers serving customer traffic.

Headline commands:

# Upload new version without deploying
wrangler versions upload

# Interactive split (prompts for percentages)
wrangler versions deploy

# Non-interactive: 90% old, 10% new
wrangler versions deploy <old-version-id>@90 <new-version-id>@10

# Promote to 100%
wrangler versions deploy <new-version-id>@100

Smoke-test a specific version in production via the Cloudflare-Workers-Version-Overrides request header (the version override applies even when its percentage is 0%).

For CI integration (OIDC trust for GitHub Actions instead of long-lived API tokens), secret rotation, and the canary-then-promote pattern, see references/deployment-and-versions.md.

Step 6 - Verify and ship

Before merge:

• wrangler types regenerated; worker-configuration.d.ts matches wrangler.jsonc
• tsc --noEmit clean
• wrangler deploy --dry-run clean (catches binding misconfigurations)
• @cloudflare/vitest-plugin tests pass
• PR description names the rejected storage alternatives and why
• PR description names the soak plan for the gradual rollout (e.g., "10% for 1h, then 50% for 1h, then 100%")
• Reviewer checklist from 401-cloudflare-workers.mdc ticked

Self-check before submitting

The high-leverage subset of the 401-cloudflare-workers.mdc reviewer checklist:

• Module Workers syntax (export default {...} or class extends WorkerEntrypoint); no addEventListener("fetch", ...)
• Env interface imported from generated worker-configuration.d.ts; satisfies ExportedHandler<Env> on the default export
• No secrets in console.log, error messages, response bodies, or thrown errors
• All fire-and-forget async work wrapped in ctx.waitUntil()
• Cloudflare resources declared as bindings (not env vars); Worker-to-Worker calls use Service Bindings + RPC (not public URLs)
• Subrequest budget considered; loops use batching where the API supports it (D1 batch(), etc.)
• No top-level await, no module-scope mutable state, no module-scope fetch()
• compatibility_date set; compatibility_flags minimal and justified
• wrangler.jsonc is source of truth; deployment from CI (not Dashboard "Edit code")
• Tests use @cloudflare/vitest-plugin (not deprecated unstable_dev)

See references/common-pitfalls.md for the full list of failure modes observed across many Workers teams, organized by symptom (cold-start regressions, intermittent state pollution, secret leaks, subrequest budget exhaustion, deployment drift).

Related

• 401-cloudflare-workers.mdc - the rule (file-scoped non-negotiables)
• 400-cloudflare.mdc - broader Cloudflare platform playbook
• 405-cloudflare-waf-rules.mdc - file-scoped WAF rule playbook
• cloud-platforms skill - cross-cloud platform patterns
• cloudflare-waf-author skill - WAF rule authoring workflow companion
• skills/typescript-javascript - general TypeScript / JavaScript patterns