gh-jezweb-claude-skills-skills-cloudflare-worker-base/references/deployment.md

Deployment Guide

Last Updated: 2025-10-20

Complete guide to deploying Cloudflare Workers with Wrangler, including CI/CD patterns and production best practices.

---

Table of Contents

1. Prerequisites
2. Wrangler Commands
3. Environment Configuration
4. CI/CD Pipelines
5. Production Best Practices
6. Monitoring and Logs

---

Prerequisites

1. Cloudflare Account

Sign up at https://dash.cloudflare.com/sign-up

2. Get Account ID

# Option 1: From dashboard
# Go to: Workers & Pages → Overview → Account ID (right sidebar)

# Option 2: Via Wrangler
wrangler whoami

Add to wrangler.jsonc:

{
  "account_id": "YOUR_ACCOUNT_ID_HERE"
}

3. Authenticate Wrangler

# Login via browser
wrangler login

# Or use API token (for CI/CD)
export CLOUDFLARE_API_TOKEN="your-token"

Create API token:

1. Go to: https://dash.cloudflare.com/profile/api-tokens
2. Click "Create Token"
3. Use template: "Edit Cloudflare Workers"
4. Copy token (only shown once!)

---

Wrangler Commands

Development

# Start local dev server (http://localhost:8787)
wrangler dev

# Local mode (no network requests to Cloudflare)
wrangler dev --local

# Custom port
wrangler dev --port 3000

# Specific environment
wrangler dev --env staging

Deployment

# Deploy to production
wrangler deploy

# Deploy to specific environment
wrangler deploy --env staging
wrangler deploy --env production

# Dry run (validate without deploying)
wrangler deploy --dry-run

# Deploy with compatibility date
wrangler deploy --compatibility-date 2025-10-11

Type Generation

# Generate TypeScript types for bindings
wrangler types

# Output to custom file
wrangler types --output-file=types/worker.d.ts

Logs

# Tail live logs
wrangler tail

# Filter by status code
wrangler tail --status error

# Filter by HTTP method
wrangler tail --method POST

# Filter by IP
wrangler tail --ip-address 1.2.3.4

# Format as JSON
wrangler tail --format json

Deployments

# List recent deployments
wrangler deployments list

# View specific deployment
wrangler deployments view DEPLOYMENT_ID

# Rollback to previous deployment
wrangler rollback --deployment-id DEPLOYMENT_ID

Secrets

# Set secret (interactive)
wrangler secret put MY_SECRET

# Set secret from file
echo "secret-value" | wrangler secret put MY_SECRET

# List secrets
wrangler secret list

# Delete secret
wrangler secret delete MY_SECRET

KV Operations

# Create KV namespace
wrangler kv namespace create MY_KV

# List namespaces
wrangler kv namespace list

# Put key-value
wrangler kv key put --namespace-id=YOUR_ID "key" "value"

# Get value
wrangler kv key get --namespace-id=YOUR_ID "key"

# List keys
wrangler kv key list --namespace-id=YOUR_ID

D1 Operations

# Create D1 database
wrangler d1 create my-database

# Execute SQL
wrangler d1 execute my-database --command "SELECT * FROM users"

# Run SQL file
wrangler d1 execute my-database --file schema.sql

# List databases
wrangler d1 list

R2 Operations

# Create R2 bucket
wrangler r2 bucket create my-bucket

# List buckets
wrangler r2 bucket list

# Upload file
wrangler r2 object put my-bucket/file.txt --file local-file.txt

# Download file
wrangler r2 object get my-bucket/file.txt --file local-file.txt

---

Environment Configuration

Single Environment (Default)

{
  "name": "my-worker",
  "account_id": "YOUR_ACCOUNT_ID",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-11",
  "vars": {
    "ENV": "production"
  },
  "kv_namespaces": [
    { "binding": "MY_KV", "id": "production-kv-id" }
  ]
}

Multiple Environments

{
  "name": "my-worker",
  "account_id": "YOUR_ACCOUNT_ID",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-11",

  // Shared configuration
  "observability": {
    "enabled": true
  },

  // Environment-specific configuration
  "env": {
    "staging": {
      "name": "my-worker-staging",
      "vars": {
        "ENV": "staging",
        "API_URL": "https://api-staging.example.com"
      },
      "kv_namespaces": [
        { "binding": "MY_KV", "id": "staging-kv-id" }
      ],
      "d1_databases": [
        { "binding": "DB", "database_name": "my-db-staging", "database_id": "staging-db-id" }
      ]
    },

    "production": {
      "name": "my-worker-production",
      "vars": {
        "ENV": "production",
        "API_URL": "https://api.example.com"
      },
      "kv_namespaces": [
        { "binding": "MY_KV", "id": "production-kv-id" }
      ],
      "d1_databases": [
        { "binding": "DB", "database_name": "my-db", "database_id": "production-db-id" }
      ],
      "routes": [
        { "pattern": "example.com/*", "zone_name": "example.com" }
      ]
    }
  }
}

Deploy:

wrangler deploy --env staging
wrangler deploy --env production

Environment Detection in Code

app.get('/api/info', (c) => {
  const env = c.env.ENV || 'development'
  const apiUrl = c.env.API_URL || 'http://localhost:3000'

  return c.json({ env, apiUrl })
})

---

CI/CD Pipelines

GitHub Actions

Create .github/workflows/deploy.yml:

name: Deploy to Cloudflare Workers

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    name: Deploy

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Deploy to Cloudflare Workers
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

With environment-specific deployment:

name: Deploy

on:
  push:
    branches:
      - main
      - staging

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Deploy to staging
        if: github.ref == 'refs/heads/staging'
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: deploy --env staging

      - name: Deploy to production
        if: github.ref == 'refs/heads/main'
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: deploy --env production

Add secrets to GitHub:

1. Go to: Repository → Settings → Secrets → Actions
2. Add CLOUDFLARE_API_TOKEN
3. Add CLOUDFLARE_ACCOUNT_ID

GitLab CI/CD

Create .gitlab-ci.yml:

image: node:20

stages:
  - test
  - deploy

test:
  stage: test
  script:
    - npm ci
    - npm test

deploy_staging:
  stage: deploy
  script:
    - npm ci
    - npx wrangler deploy --env staging
  only:
    - staging
  environment:
    name: staging

deploy_production:
  stage: deploy
  script:
    - npm ci
    - npx wrangler deploy --env production
  only:
    - main
  environment:
    name: production

Add variables to GitLab:

1. Go to: Settings → CI/CD → Variables
2. Add CLOUDFLARE_API_TOKEN (masked)
3. Add CLOUDFLARE_ACCOUNT_ID

Manual Deployment Script

Create scripts/deploy.sh:

#!/bin/bash
set -e

ENV=${1:-production}

echo "🚀 Deploying to $ENV..."

# Run tests
echo "Running tests..."
npm test

# Type check
echo "Type checking..."
npm run type-check

# Build
echo "Building..."
npm run build

# Deploy
echo "Deploying to Cloudflare..."
if [ "$ENV" = "production" ]; then
  wrangler deploy --env production
else
  wrangler deploy --env staging
fi

echo "✅ Deployment complete!"
echo "🔗 Check logs: wrangler tail --env $ENV"

Usage:

chmod +x scripts/deploy.sh
./scripts/deploy.sh staging
./scripts/deploy.sh production

---

Production Best Practices

1. Use Compatibility Dates

Always set a recent compatibility_date:

{
  "compatibility_date": "2025-10-11"
}

Why: Ensures consistent behavior and access to new features.

Update regularly: Check https://developers.cloudflare.com/workers/configuration/compatibility-dates/

2. Enable Observability

{
  "observability": {
    "enabled": true
  }
}

Provides:

• Real-time metrics
• Error tracking
• Performance monitoring

3. Set Resource Limits

{
  "limits": {
    "cpu_ms": 50  // Maximum CPU time per request (paid plan)
  }
}

4. Configure Custom Domains

{
  "routes": [
    {
      "pattern": "api.example.com/*",
      "zone_name": "example.com"
    }
  ]
}

Or via dashboard:

1. Workers & Pages → Your Worker → Triggers
2. Add Custom Domain

5. Use Secrets for Sensitive Data

# Never commit secrets to git
wrangler secret put API_KEY
wrangler secret put DATABASE_URL

// Access in code
const apiKey = c.env.API_KEY

6. Implement Rate Limiting

import { Hono } from 'hono'

const app = new Hono()

app.use('/api/*', async (c, next) => {
  const ip = c.req.header('cf-connecting-ip')
  const key = `rate-limit:${ip}`

  const count = await c.env.MY_KV.get(key)
  if (count && parseInt(count) > 100) {
    return c.json({ error: 'Rate limit exceeded' }, 429)
  }

  await c.env.MY_KV.put(key, (parseInt(count || '0') + 1).toString(), {
    expirationTtl: 60  // 1 minute
  })

  await next()
})

7. Add Health Check Endpoint

app.get('/health', (c) => {
  return c.json({
    status: 'ok',
    version: '1.0.0',
    timestamp: new Date().toISOString()
  })
})

8. Implement Error Tracking

app.onError((err, c) => {
  console.error('Error:', err)

  // Send to error tracking service
  // await sendToSentry(err)

  return c.json({
    error: 'Internal Server Error',
    requestId: c.req.header('cf-ray')
  }, 500)
})

9. Use Structured Logging

import { logger } from 'hono/logger'

app.use('*', logger())

app.get('/api/users', (c) => {
  console.log(JSON.stringify({
    level: 'info',
    message: 'Fetching users',
    userId: c.req.header('x-user-id'),
    timestamp: new Date().toISOString()
  }))

  return c.json({ users: [] })
})

10. Test Before Deploying

# Run tests
npm test

# Type check
npm run type-check

# Lint
npm run lint

# Test locally
wrangler dev --local

# Test remotely (without deploying)
wrangler dev

---

Monitoring and Logs

Real-Time Logs

# Tail all requests
wrangler tail

# Filter by status
wrangler tail --status error
wrangler tail --status ok

# Filter by method
wrangler tail --method POST

# Filter by search term
wrangler tail --search "error"

# Output as JSON
wrangler tail --format json

Analytics Dashboard

View in Cloudflare Dashboard:

1. Workers & Pages → Your Worker → Metrics
2. See:
   • Requests per second
   • Errors
   • CPU time
   • Response time

Custom Metrics

app.use('*', async (c, next) => {
  const start = Date.now()

  await next()

  const duration = Date.now() - start

  console.log(JSON.stringify({
    type: 'metric',
    name: 'request_duration',
    value: duration,
    path: c.req.path,
    method: c.req.method,
    status: c.res.status
  }))
})

External Monitoring

Use Workers Analytics Engine:

app.use('*', async (c, next) => {
  await next()

  // Write to Analytics Engine
  c.env.ANALYTICS.writeDataPoint({
    indexes: [c.req.path],
    blobs: [c.req.method, c.req.header('user-agent')],
    doubles: [Date.now(), c.res.status]
  })
})

Or send to external services:

// Send to Datadog, New Relic, etc.
await fetch('https://api.datadoghq.com/api/v1/logs', {
  method: 'POST',
  headers: {
    'DD-API-KEY': c.env.DATADOG_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'Request processed',
    status: c.res.status,
    path: c.req.path
  })
})

---

Rollback Strategy

Immediate Rollback

# List recent deployments
wrangler deployments list

# Rollback to specific deployment
wrangler rollback --deployment-id DEPLOYMENT_ID

Gradual Rollout

{
  "name": "my-worker-canary",
  "routes": [
    {
      "pattern": "example.com/*",
      "zone_name": "example.com",
      "script": "my-worker"
    }
  ]
}

1. Deploy new version to -canary worker
2. Route 10% of traffic to canary
3. Monitor metrics
4. Gradually increase to 100%
5. Promote canary to main

---

Performance Optimization

1. Minimize Bundle Size

# Check bundle size
wrangler deploy --dry-run --outdir=dist

# Analyze
ls -lh dist/

Tips:

• Avoid large dependencies
• Use dynamic imports for heavy modules
• Tree-shake unused code

2. Use Edge Caching

app.get('/api/data', async (c) => {
  const cache = caches.default
  const cacheKey = new Request(c.req.url, c.req.raw)

  let response = await cache.match(cacheKey)

  if (!response) {
    // Fetch data
    const data = await fetchData()
    response = c.json(data)

    // Cache for 5 minutes
    response.headers.set('Cache-Control', 'max-age=300')
    c.executionCtx.waitUntil(cache.put(cacheKey, response.clone()))
  }

  return response
})

3. Optimize Database Queries

// ❌ Bad: N+1 queries
for (const user of users) {
  const posts = await c.env.DB.prepare('SELECT * FROM posts WHERE user_id = ?').bind(user.id).all()
}

// ✅ Good: Single query
const posts = await c.env.DB.prepare('SELECT * FROM posts WHERE user_id IN (?)').bind(userIds).all()

---

Troubleshooting Deployments

Deployment Fails

# Check configuration
wrangler deploy --dry-run

# Verbose output
WRANGLER_LOG=debug wrangler deploy

# Check account access
wrangler whoami

Build Errors

# Clear cache
rm -rf node_modules/.wrangler
rm -rf .wrangler

# Reinstall dependencies
npm ci

# Try again
npm run deploy

Routes Not Working

# List routes
wrangler routes list

# Check zone assignment
# Dashboard → Workers & Pages → Your Worker → Triggers

---

Production-tested deployment patterns ✅ CI/CD examples validated ✅ Monitoring strategies proven ✅