Cloudflare Workers Deployment Command

<command_purpose> Perform comprehensive pre-flight checks and deploy Cloudflare Workers safely using wrangler with multi-agent validation. </command_purpose>

Introduction

<role>Cloudflare Deployment Specialist with expertise in Workers deployment, wrangler CLI, and production readiness validation</role>

This command performs thorough pre-deployment validation, runs all necessary checks, and safely deploys your Worker to Cloudflare's edge network.

Prerequisites

<requirements> - Cloudflare account with Workers enabled - wrangler CLI installed (`npm install -g wrangler`) - Authenticated with Cloudflare (`wrangler login`) - Valid `wrangler.toml` configuration - Clean git working directory (recommended) </requirements>

Deployment Target

<deployment_target> #$ARGUMENTS </deployment_target>

Supported targets:

• Empty (default) - Deploy to production
• --env staging - Deploy to staging environment
• --env preview - Deploy to preview environment
• --dry-run - Perform all checks without deploying

Main Tasks

1. Pre-Flight Checks (Critical - Must Pass)

<critical_requirement> ALL pre-flight checks must pass before deployment. No exceptions. </critical_requirement>

Phase 1: Configuration Validation

<thinking> First, validate the wrangler.toml configuration and ensure all required settings are present. </thinking>

Checks to perform:

1. Verify wrangler.toml exists

   if [ ! -f wrangler.toml ]; then
     echo "❌ CRITICAL: wrangler.toml not found"
     exit 1
   fi
   

2. Validate required fields

   • Task binding-context-analyzer(deployment target)
     • Parse wrangler.toml
     • Verify all bindings have valid IDs
     • Check compatibility_date is 2025-09-15 or later (required for remote bindings GA)
     • Verify all bindings have remote = true configured for development
     • Validate name, main, and account_id fields

3. Check authentication

   wrangler whoami
   # Verify logged in to correct account
   

Phase 2: Code Quality Checks

SKILL-based Continuous Validation (Already Active During Development):

• workers-runtime-validator SKILL: Runtime compatibility validation
• cloudflare-security-checker SKILL: Security pattern validation
• workers-binding-validator SKILL: Binding configuration validation
• edge-performance-optimizer SKILL: Performance optimization guidance
• kv-optimization-advisor SKILL: KV storage optimization
• durable-objects-pattern-checker SKILL: DO best practices validation
• cors-configuration-validator SKILL: CORS setup validation

Agent-based Comprehensive Analysis (Run for deployment validation):

Critical Checks (Must Pass):

1. Task workers-runtime-guardian(current code)

   • Deep runtime compatibility analysis
   • Complex Node.js API migration patterns
   • Package dependency analysis
   • Status: Must be CRITICAL-free (P1 issues block deployment)
   • Note: Complements workers-runtime-validator SKILL

2. Task cloudflare-security-sentinel(current code)

   • Comprehensive security audit
   • Advanced threat analysis
   • Security architecture review
   • Status: Must be CRITICAL-free (P1 security issues block deployment)
   • Note: Complements cloudflare-security-checker SKILL

3. Task binding-context-analyzer(current code)

   • Complex binding configuration analysis
   • Cross-service binding validation
   • Advanced binding patterns
   • Status: Must have no mismatches
   • Note: Complements workers-binding-validator SKILL

Important Checks (Warnings):

4. Task edge-performance-oracle(current code)

   • Comprehensive performance analysis
   • Global latency optimization
   • Advanced bundle optimization
   • Status: P2 issues generate warnings
   • Note: Complements edge-performance-optimizer SKILL

5. Task cloudflare-pattern-specialist(current code)

   • Advanced Cloudflare architecture patterns
   • Complex anti-pattern detection
   • Multi-service optimization
   • Status: P2 issues generate warnings
   • Note: Complements all storage SKILLs

Phase 3: Build & Test

<thinking> Build the Worker and run tests to ensure everything works before deployment. </thinking>

1. Clean previous builds

   rm -rf dist/ .wrangler/
   

2. Install dependencies

   npm ci  # Clean install from lock file
   

3. Type checking

   npm run typecheck || tsc --noEmit
   

4. Linting

   npm run lint
   

5. Run tests

   npm test
   

6. Build Worker

   wrangler deploy --dry-run --outdir=./dist
   

7. Analyze bundle size

   du -h ./dist/*.js
   # Warn if > 100KB, error if > 500KB
   

Phase 4: Local Testing (Optional but Recommended)

<thinking> Test the Worker locally with wrangler dev to catch runtime issues. </thinking>

Ask user: "Run local testing with wrangler dev? (recommended, y/n)"

If yes:

1. Start wrangler dev in background
2. Wait 5 seconds for startup
3. Test basic endpoints:

   curl http://localhost:8787/
   # Verify 200 response
   

4. Stop wrangler dev

2. Pre-Deployment Summary

<deliverable> Present comprehensive pre-deployment report to user </deliverable>

## Deployment Pre-Flight Summary

**Target Environment**: [production/staging/preview]
**Worker Name**: [from wrangler.toml]
**Account**: [from wrangler whoami]

### ✅ Configuration
- wrangler.toml: Valid
- Bindings: [X] configured
  - KV: [list]
  - R2: [list]
  - D1: [list]
  - DO: [list]
- Compatibility Date: [date] (✅ recent / ⚠️ outdated)

### ✅ Code Quality
- Runtime Compatibility: [PASS/FAIL]
  - Issues: [X] Critical, [Y] Important
- Security: [PASS/FAIL]
  - Issues: [X] Critical, [Y] Important
- Binding Validation: [PASS/FAIL]
  - Mismatches: [count]

### ✅ Build
- TypeScript: [PASS/FAIL]
- Linting: [PASS/FAIL]
- Tests: [PASS/FAIL] ([X] passed, [Y] failed)
- Bundle Size: [size] (✅ < 100KB / ⚠️ > 100KB / ❌ > 500KB)

### 🔍 Performance Analysis
- Cold Start (estimated): [X]ms
- Heavy Dependencies: [list if any]
- Warnings: [count]

### ⚠️ Blocking Issues (Must Fix)
[List any P1 issues that prevent deployment]

### ⚠️ Warnings (Recommended to Fix)
[List any P2 issues]

---
**Decision**: [READY TO DEPLOY / ISSUES MUST BE FIXED]

3. User Confirmation

<critical_requirement> Always require explicit user confirmation before deploying. </critical_requirement>

If blocking issues exist:

❌ Cannot deploy - [X] critical issues must be fixed:
1. [Issue description]
2. [Issue description]

Run /triage to create todos for these issues.

If only warnings exist:

⚠️ Ready to deploy with [X] warnings:
1. [Warning description]
2. [Warning description]

Deploy anyway? (yes/no/show-details)

If all checks pass:

✅ All checks passed. Ready to deploy.

Deploy to [environment]? (yes/no)

4. Deployment Execution

<thinking> Execute the actual deployment with appropriate wrangler commands. </thinking>

If user confirms YES:

1. Create git tag (if production)

   if [ "$environment" = "production" ]; then
     timestamp=$(date +%Y%m%d-%H%M%S)
     git tag -a "deploy-$timestamp" -m "Production deployment $timestamp"
   fi
   

2. Deploy with wrangler

   # For default/production
   wrangler deploy
   
   # For specific environment
   wrangler deploy --env $environment
   

3. Capture deployment output

   • Worker URL
   • Deployment ID
   • Custom domain (if configured)

4. Verify deployment

   # Test deployed Worker
   curl -I $worker_url
   # Verify 200 response
   

5. Post-Deployment Validation

<thinking> Verify the deployment was successful and the Worker is responding correctly. </thinking>

Run quick smoke tests:

1. Health check

   curl $worker_url/health || curl $worker_url/
   # Expect 200 status
   

2. Verify bindings accessible (if applicable)

   • Test endpoint that uses KV/R2/D1/DO
   • Verify no binding errors

3. Check Cloudflare dashboard

   wrangler tail --format json | head -n 5
   # Show first 5 requests/logs
   

6. Deployment Report

<deliverable> Final deployment summary with all details </deliverable>

## 🚀 Deployment Complete

**Environment**: [production/staging/preview]
**Deployed At**: [timestamp]
**Worker URL**: [url]
**Custom Domain**: [domain] (if configured)

### Deployment Details
- Worker Name: [name]
- Bundle Size: [size]
- Deployment ID: [id]
- Git Tag: [tag] (if production)

### Verification
- Health Check: [✅ PASS / ❌ FAIL]
- Response Time: [X]ms
- Status Code: [code]

### Next Steps
1. Monitor logs: `wrangler tail`
2. View analytics: https://dash.cloudflare.com
3. Test endpoints: [list key endpoints]

### Rollback (if needed)
```bash
# View previous deployments
wrangler deployments list

# Rollback to previous version
wrangler rollback [deployment-id]

---

Status: ✅ Deployment Successful

## Emergency Rollback

If deployment fails or issues are detected:

1. **Immediate rollback**
   ```bash
   wrangler deployments list
   wrangler rollback [previous-deployment-id]

2. Notify user

   ❌ Deployment rolled back to previous version
   Reason: [failure reason]
   
   Investigate issues:
   - Check logs: wrangler tail
   - Review errors: [error details]
   

Deployment Checklist

<checklist> Before confirming deployment, verify:

• wrangler.toml is valid and complete
• All bindings have valid IDs
• No Node.js APIs in code
• No hardcoded secrets
• TypeScript compiles without errors
• Linting passes
• All tests pass
• Bundle size is acceptable (< 500KB)
• No CRITICAL (P1) issues from agents
• User has confirmed deployment
• Correct environment selected
• Git working directory is clean (if production) </checklist>

Environment-Specific Notes

Production Deployment

• Requires explicit confirmation
• Creates git tag for tracking
• Runs full validation suite
• Monitors initial requests

Staging Deployment

• Slightly relaxed validation (P2 warnings allowed)
• No git tag created
• Faster deployment process

Preview Deployment

• Minimal validation
• Quick iteration for testing
• Temporary URL

Troubleshooting

Common Issues

Issue: "Error: Could not find binding {name}" Solution: Run Task binding-context-analyzer to verify wrangler.toml

Issue: "Error: Bundle size too large" Solution: Run Task edge-performance-oracle for optimization recommendations

Issue: "Error: Authentication failed" Solution: Run wrangler login to re-authenticate

Issue: "Error: Worker exceeded CPU limit" Solution: Check for blocking operations, infinite loops, or heavy computation

Success Criteria

✅ Deployment considered successful when:

• All pre-flight checks pass (no P1 issues)
• Worker deploys without errors
• Health check returns 200
• No immediate runtime errors in logs
• Rollback capability confirmed available

Notes

• Always test in staging before production
• Monitor logs for first 5-10 minutes after deployment
• Keep rollback procedure ready
• Document any configuration changes
• Update team on deployment status

---

Remember: It's better to fail pre-flight checks than to deploy broken code. Every check exists to prevent production issues.