cloudflare-deploy

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

1. **Verify auth and account.**
   ```bash
   npx wrangler whoami
   npx wrangler types  # regenerate Env type bindings
   ```
2. **Validate config per environment.** Diff bindings vs. account state:
   ```bash
   npx wrangler kv namespace list
   npx wrangler r2 bucket list
   npx wrangler d1 list
   ```
   Ensure each `[env.<name>]` block has matching IDs.
3. **Set secrets per environment** (idempotent — overwrites):
   ```bash
   echo "$STRIPE_KEY" | npx wrangler secret put STRIPE_KEY --env production
   ```
4. **Build & test locally** against the real edge:
   ```bash
   npm run build
   npm test
   npx wrangler dev --remote --env staging
   ```
5. **Upload a version (no traffic shift)** — produces a version ID:
   ```bash
   npx wrangler versions upload --env production --message "$(git rev-parse --short HEAD): ${COMMIT_SUBJECT}"
   ```
6. **Deploy gradually** to 10% → observe → 100%:
   ```bash
   # Send 10% to new version, 90% stays on previous
   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:
   ```bash
   npx wrangler tail --env production --format pretty --status error
   ```
7. **Promote to 100%** after error rate and p95 latency stay within SLO:
   ```bash
   npx wrangler versions deploy --env production <NEW_VERSION_ID>@100% --yes
   ```
8. **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.
9. **Verify production.** Hit health route, sample critical paths, check Analytics Engine / Logs:
   ```bash
   curl -fsS https://api.example.com/healthz
   ```
10. **Rollback (single command).** Re-deploy the previous version ID at 100%:
    ```bash
    npx wrangler versions deploy --env production <PREV_VERSION_ID>@100% --yes
    ```
11. **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:

1. Version ID uploaded and version ID currently serving traffic.
2. Gradual rollout plan and observed metrics at each stage (error rate, p50/p95/p99).
3. Bindings/secrets diff applied (created, updated, removed).
4. Health-check results for production endpoints.
5. Exact rollback command pre-filled with previous version ID.

## Authoritative References

- Wrangler commands: https://developers.cloudflare.com/workers/wrangler/commands/
- Workers gradual deployments: https://developers.cloudflare.com/workers/configuration/versions-and-deployments/gradual-deployments/
- Workers configuration: https://developers.cloudflare.com/workers/wrangler/configuration/
- Workers Assets (static sites): https://developers.cloudflare.com/workers/static-assets/
- Pages → Workers migration: https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/

From SwapnilPopat/ai-assistant-skills, MIT.

More from SwapnilPopat/ai-assistant-skills