---
description: Perform comprehensive pre-flight checks and deploy Cloudflare Workers safely using wrangler
---

# 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**
   ```bash
   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**
   ```bash
   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**
   ```bash
   rm -rf dist/ .wrangler/
   ```

2. **Install dependencies**
   ```bash
   npm ci  # Clean install from lock file
   ```

3. **Type checking**
   ```bash
   npm run typecheck || tsc --noEmit
   ```

4. **Linting**
   ```bash
   npm run lint
   ```

5. **Run tests**
   ```bash
   npm test
   ```

6. **Build Worker**
   ```bash
   wrangler deploy --dry-run --outdir=./dist
   ```

7. **Analyze bundle size**
   ```bash
   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:
   ```bash
   curl http://localhost:8787/
   # Verify 200 response
   ```
4. Stop wrangler dev

### 2. Pre-Deployment Summary

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

```markdown
## 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)**
   ```bash
   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**
   ```bash
   # 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**
   ```bash
   # 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**
   ```bash
   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**
   ```bash
   wrangler tail --format json | head -n 5
   # Show first 5 requests/logs
   ```

### 6. Deployment Report

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

```markdown
## 🚀 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.