Cloudflare Production Builder
Apply this guidance proportionally. It is a production reasoning aid, not a
mandatory ceremony layer. Stay within the user's requested operation and do not
turn a diagnosis or recovery into an architecture program.
Choose the operating mode
- Answer or diagnose: inspect only the evidence needed to explain the
behavior. Do not mutate or design a replacement unless asked.
- Recover: restore a known-good capability with the smallest supported,
reversible operation. Preserve evidence and defer refactoring.
- Change or migrate: design compatibility, durability, rollout, verification,
and rollback for the surfaces actually affected.
Do not mix recovery and refactoring in one production operation.
Core contract
- Identify authoritative state, the coordination key, the durability boundary,
and user-visible completion.
- Treat source, build, upload, configuration, migration, traffic, route,
stateful lifecycle, and live behavior as separate facts only when the task
depends on those surfaces.
- Prefer immutable artifacts and conditional pointer changes. Make external
mutations idempotent, fenced, conditional, or compensatable.
- Classify errors before retrying. Persist terminal domain failures; bound
transient retries; read authoritative provider state after an ambiguous
mutation before replay. Do not turn artifact verification into a resumable
controller unless the product operation itself requires durable execution.
- Preserve accepted work across handoff failures. Use a durable record and a
repair path when an initiating request can disappear.
- Verify the owning live path and exact identity after a production mutation.
Use precise language such as
version uploaded, traffic switched, and
live smoke passed.
For SHA-derived, write-once release artifacts, reconcile means bounded
provider readback and a fail-closed decision. Adopt an existing artifact only
when every immutable property matches. Never repair a mismatch in place, add a
durable current-artifact pointer, or create another publication authority merely
to make image, host, application, namespace, or version creation retryable.
Traffic publication and rollback should switch one recorded immutable pointer
when the topology supports it; build-time artifact preparation stays outside
that publication path.
Prefer provider-native hot paths
For a measured Cloudflare bottleneck, identify the existing binding, bulk API,
or authenticated REST operation before starting Wrangler or making a network
round trip per item. Consider R2 bindings or direct REST uploads with an
existing scoped token, D1 batch() or set-based SQL, KV bulk writes, Queue
sendBatch(), direct Workers version/deployment readbacks, content-addressed
asset reuse, and coalesced Durable Object writes when semantics permit.
Keep concurrency and transient retries bounded; preserve credential scope,
provider limits, metadata, immutable verification, publication ordering, and
rollback. Do not introduce S3 credentials, broader permissions, or a new
service merely to optimize transport. Keep Wrangler for infrequent complex
deployment mutations unless a supported API preserves every safety invariant;
verify provider response schemas with a real canary.
Proportional workflow
- Inspect current code and provisioned state for the touched surface. Resolve
the exact account, environment, resource, bindings, and live version before
mutation.
- State the intended authority and repair/rollback path. For simple work, one
sentence is enough.
- Run focused local or remote checks that can falsify the change. Do not add
unrelated global gates.
- When authorized to deploy, upload and inspect before switching when the
provider supports it. Use a verification path supported by the topology.
- After mutation, verify only the affected rollout axes plus the user-visible
capability. Record exact identities and rollback evidence.
When a cutover temporarily retains an old Worker, Durable Object namespace, or
container application as the exact rollback target, leave it byte-for-byte and
configuration-for-configuration unchanged through the rollback-compatibility
window. Retention is temporary compatibility, not permanent dual-running.
Remove the old artifact only in a separate bounded cleanup after live and
rollback compatibility have been proven; do not hide that deletion inside the
cutover or ordinary artifact garbage collection.
Pause when the exact production target, current state, retry safety, or rollback
target cannot be resolved. A blocker in an unrelated surface is not permission
to broaden the operation.
Integrate preview and newly launched capabilities safely
When a preview or newly launched Cloudflare capability materially improves the
design, use it deliberately rather than trusting remembered APIs:
- Retrieve current first-party docs and changelog entries at action time. Note
the capability's maturity, launch date, documented limits, and production
support status.
- Inspect the installed package's
package.json, README/examples, exports, and
.d.ts files. Installed types are the compilation contract; marketing docs
are not.
- Put the preview surface behind a narrow adapter so churn does not spread
through domain code. Keep a supported fallback or an explicit failure mode
when the capability is not production-suitable.
- Pin the exact package version during the proving release. Compile and build
immediately after wiring each preview primitive; do not defer integration
feedback until the full system exists.
- Inspect generated artifacts, not just source: Worker entrypoint, generated
Wrangler config, asset directories, binding names, Durable Object migrations,
and the path the release system will actually upload.
- Scan the final bundle for
.dev.vars*, .env*, credentials, and unexpected
local files. Fail or scrub the build before packaging; a clean Git ignore is
not evidence that build output is clean.
- Record the exact version and local evidence separately from live evidence.
Do not claim production behavior until the exact uploaded artifact, bindings,
routes, migrations, and owning live path have passed smoke verification.
Treat type casts between preview packages as an adapter concern and test the
runtime seam. Structurally similar workspace, loader, or RPC types from different
package versions can compile only after a cast while still disagreeing at
runtime.
Load references selectively
- primitive-selection.md: use when the
product or coordination primitive is genuinely undecided.
- durable-execution.md: use for asynchronous
handoffs, retries, queues, Workflows, or long-running external work.
- storage-and-caching.md: use for storage,
cache, and authorization boundaries.
- deployments-and-migrations.md: use
for multi-surface rollout, schema or Durable Object lifecycle, and rollback.
- multitenant-hosting-and-security.md:
use when customer-controlled code, public-fork changes, or another adversarial
execution boundary requires tenant isolation. Do not load it solely because a
preview comes from a same-repository PR by trusted collaborators.
- observability-testing-and-cost.md:
use when adding or reviewing telemetry, test layers, or spend controls,
including CI build artifacts. Default large temporary build packages to
three-day retention; keep small release receipts longer. The reference covers
local validation, batched pushes, and selecting builds by actual dependencies.
Retrieve current first-party Cloudflare documentation before relying on API
signatures, configuration, limits, pricing, retention, or product support.
1---2name: cloudflare-production-builder3description: Design, review, debug, migrate, or deploy production systems on Cloudflare Workers and related Developer Platform products. Use for material architecture, durability, release, migration, rollback, or live-verification decisions across Workers, Durable Objects, D1, R2, Queues, Workflows, bindings, and routes.4metadata:5 source: https://skillmd.com/skills/swyxio/cloudflare-production-builder6---78# Cloudflare Production Builder910Apply this guidance proportionally. It is a production reasoning aid, not a11mandatory ceremony layer. Stay within the user's requested operation and do not12turn a diagnosis or recovery into an architecture program.1314## Choose the operating mode1516- **Answer or diagnose:** inspect only the evidence needed to explain the17 behavior. Do not mutate or design a replacement unless asked.18- **Recover:** restore a known-good capability with the smallest supported,19 reversible operation. Preserve evidence and defer refactoring.20- **Change or migrate:** design compatibility, durability, rollout, verification,21 and rollback for the surfaces actually affected.2223Do not mix recovery and refactoring in one production operation.2425## Core contract26271. Identify authoritative state, the coordination key, the durability boundary,28 and user-visible completion.292. Treat source, build, upload, configuration, migration, traffic, route,30 stateful lifecycle, and live behavior as separate facts only when the task31 depends on those surfaces.323. Prefer immutable artifacts and conditional pointer changes. Make external33 mutations idempotent, fenced, conditional, or compensatable.344. Classify errors before retrying. Persist terminal domain failures; bound35 transient retries; read authoritative provider state after an ambiguous36 mutation before replay. Do not turn artifact verification into a resumable37 controller unless the product operation itself requires durable execution.385. Preserve accepted work across handoff failures. Use a durable record and a39 repair path when an initiating request can disappear.406. Verify the owning live path and exact identity after a production mutation.41 Use precise language such as `version uploaded`, `traffic switched`, and42 `live smoke passed`.4344For SHA-derived, write-once release artifacts, `reconcile` means bounded45provider readback and a fail-closed decision. Adopt an existing artifact only46when every immutable property matches. Never repair a mismatch in place, add a47durable current-artifact pointer, or create another publication authority merely48to make image, host, application, namespace, or version creation retryable.49Traffic publication and rollback should switch one recorded immutable pointer50when the topology supports it; build-time artifact preparation stays outside51that publication path.5253## Prefer provider-native hot paths5455For a measured Cloudflare bottleneck, identify the existing binding, bulk API,56or authenticated REST operation before starting Wrangler or making a network57round trip per item. Consider R2 bindings or direct REST uploads with an58existing scoped token, D1 `batch()` or set-based SQL, KV bulk writes, Queue59`sendBatch()`, direct Workers version/deployment readbacks, content-addressed60asset reuse, and coalesced Durable Object writes when semantics permit.6162Keep concurrency and transient retries bounded; preserve credential scope,63provider limits, metadata, immutable verification, publication ordering, and64rollback. Do not introduce S3 credentials, broader permissions, or a new65service merely to optimize transport. Keep Wrangler for infrequent complex66deployment mutations unless a supported API preserves every safety invariant;67verify provider response schemas with a real canary.6869## Proportional workflow70711. Inspect current code and provisioned state for the touched surface. Resolve72 the exact account, environment, resource, bindings, and live version before73 mutation.742. State the intended authority and repair/rollback path. For simple work, one75 sentence is enough.763. Run focused local or remote checks that can falsify the change. Do not add77 unrelated global gates.784. When authorized to deploy, upload and inspect before switching when the79 provider supports it. Use a verification path supported by the topology.805. After mutation, verify only the affected rollout axes plus the user-visible81 capability. Record exact identities and rollback evidence.8283When a cutover temporarily retains an old Worker, Durable Object namespace, or84container application as the exact rollback target, leave it byte-for-byte and85configuration-for-configuration unchanged through the rollback-compatibility86window. Retention is temporary compatibility, not permanent dual-running.87Remove the old artifact only in a separate bounded cleanup after live and88rollback compatibility have been proven; do not hide that deletion inside the89cutover or ordinary artifact garbage collection.9091Pause when the exact production target, current state, retry safety, or rollback92target cannot be resolved. A blocker in an unrelated surface is not permission93to broaden the operation.9495## Integrate preview and newly launched capabilities safely9697When a preview or newly launched Cloudflare capability materially improves the98design, use it deliberately rather than trusting remembered APIs:991001. Retrieve current first-party docs and changelog entries at action time. Note101 the capability's maturity, launch date, documented limits, and production102 support status.1032. Inspect the installed package's `package.json`, README/examples, exports, and104 `.d.ts` files. Installed types are the compilation contract; marketing docs105 are not.1063. Put the preview surface behind a narrow adapter so churn does not spread107 through domain code. Keep a supported fallback or an explicit failure mode108 when the capability is not production-suitable.1094. Pin the exact package version during the proving release. Compile and build110 immediately after wiring each preview primitive; do not defer integration111 feedback until the full system exists.1125. Inspect generated artifacts, not just source: Worker entrypoint, generated113 Wrangler config, asset directories, binding names, Durable Object migrations,114 and the path the release system will actually upload.1156. Scan the final bundle for `.dev.vars*`, `.env*`, credentials, and unexpected116 local files. Fail or scrub the build before packaging; a clean Git ignore is117 not evidence that build output is clean.1187. Record the exact version and local evidence separately from live evidence.119 Do not claim production behavior until the exact uploaded artifact, bindings,120 routes, migrations, and owning live path have passed smoke verification.121122Treat type casts between preview packages as an adapter concern and test the123runtime seam. Structurally similar workspace, loader, or RPC types from different124package versions can compile only after a cast while still disagreeing at125runtime.126127## Load references selectively128129- [primitive-selection.md](references/primitive-selection.md): use when the130 product or coordination primitive is genuinely undecided.131- [durable-execution.md](references/durable-execution.md): use for asynchronous132 handoffs, retries, queues, Workflows, or long-running external work.133- [storage-and-caching.md](references/storage-and-caching.md): use for storage,134 cache, and authorization boundaries.135- [deployments-and-migrations.md](references/deployments-and-migrations.md): use136 for multi-surface rollout, schema or Durable Object lifecycle, and rollback.137- [multitenant-hosting-and-security.md](references/multitenant-hosting-and-security.md):138 use when customer-controlled code, public-fork changes, or another adversarial139 execution boundary requires tenant isolation. Do not load it solely because a140 preview comes from a same-repository PR by trusted collaborators.141- [observability-testing-and-cost.md](references/observability-testing-and-cost.md):142 use when adding or reviewing telemetry, test layers, or spend controls,143 including CI build artifacts. Default large temporary build packages to144 three-day retention; keep small release receipts longer. The reference covers145 local validation, batched pushes, and selecting builds by actual dependencies.146147Retrieve current first-party Cloudflare documentation before relying on API148signatures, configuration, limits, pricing, retention, or product support.