| name | cloudflare-deploy |
| description | Deploy Cloudflare Workers, Pages, and Workers-with-static-assets safely using Wrangler 4.x with versioned uploads, gradual deployments, preview/production environments, secret bindings, observability, and one-command rollback. Use when shipping edge workloads, API routes, or full-stack apps to Cloudflare. Requires CLOUDFLARE_API_TOKEN with scoped permissions or an authenticated Wrangler session. |
Cloudflare Deploy
Ship Cloudflare Workers, Pages, and Workers Assets sites with versioned uploads, gradual rollouts, and verified post-deploy health.
Stack Baseline (2026)
| Concern | Choice | Notes |
|---|
| CLI | Wrangler ≥4.0 | Single config replaces legacy pages deploy for new projects (Workers Assets) |
| Config | wrangler.toml or wrangler.jsonc | JSONC supports comments and is the new recommended format |
| Runtime | compatibility_date ≤30 days old; pin nodejs_compat flag if using Node APIs | |
| Deploy model | Versioned uploads (wrangler versions upload) → gradual deploy (wrangler versions deploy) | Replaces direct wrangler deploy for production |
| Bindings | KV, R2, D1, Durable Objects, Queues, Hyperdrive, Workers AI, Vectorize, Service bindings | Each must exist in target account/env |
| Secrets | wrangler secret put NAME (per env) or secrets_store_secrets binding | Never commit values |
| Static assets | [assets] block in wrangler.toml (replaces Pages for new sites) | |
| Observability | [observability] enabled = true | Sends logs/metrics to Cloudflare dashboard |
| Token scopes | Workers Scripts:Edit, Workers Routes:Edit, Account Settings:Read, Workers KV Storage:Edit (as needed) | Least privilege per pipeline |
| Local dev | wrangler dev --remote | Runs against real Cloudflare network |
When to Use
- Deploying Workers (HTTP, scheduled, queue consumer, Durable Object).
- Deploying static or full-stack sites via Workers Assets.
- Migrating Pages projects to Workers Assets.
- Promoting a vetted preview to production with gradual rollout.
Prerequisites
CLOUDFLARE_API_TOKEN exported (scoped, not Global API Key) or wrangler login session active.- Account ID known:
wrangler whoami.
- Target environment defined under
[env.staging] / [env.production] in config.
- All bindings (KV namespace IDs, R2 bucket names, D1 database IDs, DO class+script bindings) created in target account.
- CI runner has Node ≥20 and
npx wrangler available.
Instructions
- Verify auth and account.
npx wrangler whoami
npx wrangler types
- Validate config per environment. Diff bindings vs. account state:
npx wrangler kv namespace list
npx wrangler r2 bucket list
npx wrangler d1 list
Ensure each [env.<name>] block has matching IDs.
- Set secrets per environment (idempotent — overwrites):
echo "$STRIPE_KEY" | npx wrangler secret put STRIPE_KEY --env production
- Build & test locally against the real edge:
npm run build
npm test
npx wrangler dev --remote --env staging
- Upload a version (no traffic shift) — produces a version ID:
npx wrangler versions upload --env production --message "$(git rev-parse --short HEAD): ${COMMIT_SUBJECT}"
- Deploy gradually to 10% → observe → 100%:
npx wrangler versions deploy --env production \
<NEW_VERSION_ID>@10% <PREV_VERSION_ID>@90% --yes
Monitor for 5–15 min using wrangler tail and Workers Analytics:
npx wrangler tail --env production --format pretty --status error
- Promote to 100% after error rate and p95 latency stay within SLO:
npx wrangler versions deploy --env production <NEW_VERSION_ID>@100% --yes
- For Pages / Workers Assets sites with framework adapters (Next, Astro, Remix, SvelteKit), build via the adapter then
wrangler deploy. Validate _headers, _redirects, and [assets].not_found_handling behavior on preview URL first.
- Verify production. Hit health route, sample critical paths, check Analytics Engine / Logs:
curl -fsS https://api.example.com/healthz
- Rollback (single command). Re-deploy the previous version ID at 100%:
npx wrangler versions deploy --env production <PREV_VERSION_ID>@100% --yes
- Tag the deploy in your release tracker (Sentry release, GitHub deployment, etc.) using the version ID for traceability.
Common Pitfalls
| Pitfall | Impact | Fix |
|---|
Using wrangler deploy instead of versioned uploads | No instant rollback target | Use versions upload + versions deploy |
compatibility_date years stale | Missing runtime fixes; subtle behavior drift | Bump within 30 days; test on preview |
| Same KV/R2 binding ID across staging+prod | Cross-env data corruption | Distinct IDs per [env.*] block |
Storing secrets in vars block | Plaintext in config & dashboard | Use wrangler secret put or Secrets Store |
| Global API Key in CI | Full account compromise on token leak | Scoped API Token only |
Skipping wrangler types regen | Type errors hide binding drift at build | Regenerate after every binding change |
| Deploying without gradual ramp | Bad version hits 100% of traffic instantly | Always 10% canary first |
Missing nodejs_compat flag with Node imports | Runtime crash on import { Buffer } etc. | Add compatibility_flags = ["nodejs_compat"] |
| Pages project for new full-stack work | Legacy path; missing latest features | Use Workers + Assets |
Ignoring wrangler tail after deploy | Errors visible only via user reports | Tail for ≥5 min on every prod deploy |
Output Format
Report to caller:
- Version ID uploaded and version ID currently serving traffic.
- Gradual rollout plan and observed metrics at each stage (error rate, p50/p95/p99).
- Bindings/secrets diff applied (created, updated, removed).
- Health-check results for production endpoints.
- Exact rollback command pre-filled with previous version ID.
Authoritative References
