Cloudflare Worker Deployment

Overview

Deploy any project as a Cloudflare Worker. Handles wrangler configuration, secret management, custom domain routing, and deployment verification.

Core principle: Zero-config for simple cases, full control for complex ones.

Trigger: /popkit:deploy setup cloudflare-worker command

Prerequisites

Cloudflare account with API token
CLOUDFLARE_API_TOKEN environment variable set
wrangler installed (npm install -g wrangler or npx wrangler)

Critical Rules

ALWAYS verify token first - Check API access before any operations
NEVER deploy without health check - Verify endpoint responds after deploy
Use environment-specific configs - Dev vs production settings
Set secrets via wrangler - Never hardcode credentials
Configure custom domains properly - DNS + route configuration

Process

Step 1: Verify Cloudflare Access

import os
import sys

# Check for API token
token = os.environ.get("CLOUDFLARE_API_TOKEN")
if not token:
    print("ERROR: CLOUDFLARE_API_TOKEN not set")
    print("Set via: export CLOUDFLARE_API_TOKEN=your-token")
    sys.exit(1)

# Verify token is valid
# Use hooks/utils/cloudflare_api.py
from hooks.utils.cloudflare_api import CloudflareClient
client = CloudflareClient()
valid, message = client.verify_token()

if not valid:
    print(f"ERROR: Token invalid - {message}")
    sys.exit(1)

print("Cloudflare access verified")

Step 2: Detect Project Type

from pathlib import Path

def detect_worker_type():
    """Detect what kind of Worker to create."""
    cwd = Path.cwd()

    # Check for existing wrangler.toml
    if (cwd / "wrangler.toml").exists():
        return "existing"

    # Check for TypeScript
    if (cwd / "tsconfig.json").exists():
        if (cwd / "package.json").exists():
            import json
            with open(cwd / "package.json") as f:
                pkg = json.load(f)
            deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}

            if "hono" in deps:
                return "hono-ts"
            elif "itty-router" in deps:
                return "itty-ts"
            else:
                return "typescript"

    # Check for Python
    if (cwd / "requirements.txt").exists() or (cwd / "pyproject.toml").exists():
        return "python"

    # Default to JavaScript
    return "javascript"

Step 3: User Configuration

Use AskUserQuestion to gather deployment details:

Use AskUserQuestion tool with:
- question: "What name should the Worker have?"
- header: "Worker Name"
- options:
  - label: "Use directory name"
    description: "Name based on current folder"
  - label: "Custom name"
    description: "I'll specify a name"
- multiSelect: false

Use AskUserQuestion tool with:
- question: "Do you want to configure a custom domain?"
- header: "Domain"
- options:
  - label: "Yes, configure domain"
    description: "Set up custom domain routing"
  - label: "No, use workers.dev"
    description: "Access via worker-name.workers.dev"
- multiSelect: false

Step 4: Generate wrangler.toml

Basic Template (JavaScript/TypeScript)

name = "{{worker_name}}"
main = "src/index.ts"
compatibility_date = "2024-12-01"
compatibility_flags = ["nodejs_compat"]

[vars]
ENVIRONMENT = "production"

# Uncomment for custom domain:
# routes = [
#   { pattern = "api.example.com/*", zone_name = "example.com" }
# ]

# KV Namespaces (uncomment if needed):
# [[kv_namespaces]]
# binding = "MY_KV"
# id = "your-kv-namespace-id"

# D1 Database (uncomment if needed):
# [[d1_databases]]
# binding = "DB"
# database_name = "my-database"
# database_id = "your-d1-database-id"

# Durable Objects (uncomment if needed):
# [[durable_objects.bindings]]
# name = "MY_DO"
# class_name = "MyDurableObject"

# R2 Bucket (uncomment if needed):
# [[r2_buckets]]
# binding = "MY_BUCKET"
# bucket_name = "my-bucket"

Hono Framework Template

name = "{{worker_name}}"
main = "src/index.ts"
compatibility_date = "2024-12-01"
compatibility_flags = ["nodejs_compat"]

[vars]
ENVIRONMENT = "production"

# For Hono's getConnInfo() helper
# Requires Workers paid plan for certain features

Python Worker Template

name = "{{worker_name}}"
main = "src/entry.py"
compatibility_date = "2024-12-01"
compatibility_flags = ["python_workers"]

[vars]
ENVIRONMENT = "production"

Step 5: Create Entry Point (if missing)

TypeScript with Hono

// src/index.ts
import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { logger } from 'hono/logger';

type Bindings = {
  ENVIRONMENT: string;
  // Add your bindings here
};

const app = new Hono<{ Bindings: Bindings }>();

// Middleware
app.use('*', cors());
app.use('*', logger());

// Routes
app.get('/', (c) => {
  return c.json({
    service: '{{worker_name}}',
    version: '1.0.0',
  });
});

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

// Error handling
app.onError((err, c) => {
  console.error('Request error:', err);
  return c.json({ error: 'Internal server error' }, 500);
});

app.notFound((c) => {
  return c.json({ error: 'Not found' }, 404);
});

export default app;

JavaScript (Basic)

// src/index.js
export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);

    if (url.pathname === '/health') {
      return Response.json({
        status: 'ok',
        timestamp: new Date().toISOString(),
      });
    }

    if (url.pathname === '/') {
      return Response.json({
        service: '{{worker_name}}',
        version: '1.0.0',
      });
    }

    return Response.json({ error: 'Not found' }, { status: 404 });
  },
};

Step 6: Configure Custom Domain (if requested)

from hooks.utils.cloudflare_api import CloudflareClient

def setup_custom_domain(domain: str, subdomain: str, worker_name: str):
    """Configure DNS and wrangler for custom domain."""
    client = CloudflareClient()

    # Find zone
    zone = client.get_zone_by_name(domain)
    if not zone:
        raise ValueError(f"Zone not found: {domain}")

    # Check if record exists
    full_domain = f"{subdomain}.{domain}" if subdomain else domain
    records = client.list_dns_records(zone.id, name=full_domain)

    if records:
        # Update existing record
        print(f"Updating existing DNS record for {full_domain}")
        client.update_dns_record(
            zone.id,
            records[0].id,
            content=f"{worker_name}.workers.dev",
            proxied=True,
            comment=f"Worker: {worker_name}"
        )
    else:
        # Create new record
        print(f"Creating DNS record for {full_domain}")
        client.create_dns_record(
            zone.id,
            record_type="CNAME",
            name=subdomain or "@",
            content=f"{worker_name}.workers.dev",
            proxied=True,
            comment=f"Worker: {worker_name}"
        )

    return full_domain, zone.name

Update wrangler.toml with route:

import toml

def add_route_to_wrangler(domain: str, zone_name: str):
    """Add custom domain route to wrangler.toml."""
    with open("wrangler.toml") as f:
        config = toml.load(f)

    config["routes"] = [
        {"pattern": f"{domain}/*", "zone_name": zone_name}
    ]

    with open("wrangler.toml", "w") as f:
        toml.dump(config, f)

Step 7: Set Secrets

Use AskUserQuestion tool with:
- question: "Do you need to configure secrets for this Worker?"
- header: "Secrets"
- options:
  - label: "Yes, set secrets"
    description: "Configure environment secrets"
  - label: "No secrets needed"
    description: "Skip secret configuration"
- multiSelect: false

If yes, guide user through:

# Set secrets securely (prompts for value)
npx wrangler secret put SECRET_NAME

# Or bulk from .env.local
npx wrangler secret bulk .env.local

Step 8: Deploy

# Install dependencies if needed
npm install

# Deploy to Cloudflare
npx wrangler deploy

Step 9: Verify Deployment

import urllib.request
import time

def verify_deployment(url: str, max_retries: int = 5):
    """Verify Worker is responding after deployment."""
    health_url = f"{url}/health"

    for attempt in range(max_retries):
        try:
            with urllib.request.urlopen(health_url, timeout=10) as response:
                if response.status == 200:
                    data = response.read().decode()
                    print(f"Health check passed: {data}")
                    return True
        except Exception as e:
            print(f"Attempt {attempt + 1}/{max_retries}: {e}")
            time.sleep(2)

    return False

# Verify
if custom_domain:
    verify_deployment(f"https://{custom_domain}")
else:
    verify_deployment(f"https://{worker_name}.workers.dev")

Output Format

Cloudflare Worker Deployment
════════════════════════════

[1/6] Verifying Cloudflare access...
      ✓ API token valid
      ✓ Account: your-account-name

[2/6] Detecting project type...
      ✓ Type: Hono (TypeScript)
      ✓ Entry: src/index.ts

[3/6] Generating wrangler.toml...
      ✓ Worker name: popkit-cloud-api
      ✓ Compatibility: 2024-12-01
      ✓ Node.js compat enabled
      → wrangler.toml created

[4/6] Configuring custom domain...
      ✓ Domain: api.thehouseofdeals.com
      ✓ DNS record created (CNAME → workers.dev)
      ✓ Route added to wrangler.toml

[5/6] Deploying to Cloudflare...
      ✓ Build successful
      ✓ Upload: 309 KiB (gzip)
      ✓ Version: d8efac8e-87c2-4198-a808-6fb9d5b4002d

[6/6] Verifying deployment...
      ✓ Health check passed
      ✓ Response time: 45ms

Deployment Complete!
════════════════════
Worker URL: https://api.thehouseofdeals.com
Workers.dev: https://popkit-cloud-api.workers.dev
Dashboard: https://dash.cloudflare.com/workers/popkit-cloud-api

Quick Commands:
  wrangler tail          # Live logs
  wrangler dev           # Local development
  wrangler deployments   # View deployment history

Troubleshooting

Issue	Solution
"Authentication error"	Verify CLOUDFLARE_API_TOKEN is set and valid
"Zone not found"	Check domain is in your Cloudflare account
"Build failed"	Run `npm run build` locally first
"Secret not found"	Set via `wrangler secret put NAME`
"Route conflict"	Remove conflicting routes in dashboard

Integration

Command: /popkit:deploy setup cloudflare-worker

Utility: Uses hooks/utils/cloudflare_api.py for API operations

Followed by:

/popkit:deploy validate - Pre-deployment checks
/popkit:deploy execute - Deploy the Worker

Related Skills

Skill	Relationship
`pop-cloudflare-pages-deploy`	For static sites/SPAs
`pop-cloudflare-dns-manage`	DNS-only operations
`pop-deploy-init`	Initialize deployment config

cloudflare-worker-deploy