enuno/cloudflare-workers

Cloudflare Workers Skill

Comprehensive assistance with Cloudflare Workers development, including the workerd runtime, Wrangler CLI, Miniflare local development, C3 project scaffolding, Rust SDK (workers-rs), and official starter templates.

When to Use This Skill

This skill should be triggered when:

• Creating new Cloudflare Workers projects
• Working with Wrangler CLI commands
• Developing Workers locally with Miniflare
• Deploying Workers to Cloudflare's edge network
• Configuring Workers KV, Durable Objects, R2, D1, or Queues
• Debugging and testing Workers
• Setting up CI/CD for Workers
• Writing Workers in Rust with workers-rs
• Building WebAssembly-based Workers
• Self-hosting Workers with workerd runtime
• Understanding the Workers runtime architecture

Quick Start

Create a New Project (C3)

# Interactive project creation
npm create cloudflare@latest

# Create with specific framework
npm create cloudflare@latest my-app -- --framework=next
npm create cloudflare@latest my-api -- --framework=hono

# Accept defaults (quick start)
npm create cloudflare@latest my-worker -- -y

# TypeScript or JavaScript
npm create cloudflare@latest my-worker -- --lang=ts
npm create cloudflare@latest my-worker -- --lang=js

Supported Frameworks

C3 supports: Angular, Astro, Docusaurus, Gatsby, Hono, Next.js, Nuxt, Qwik, React, Remix, SolidStart, SvelteKit, Vue

C3 Options

| Option | Description | |--------|-------------| | --framework | Specify web framework (next, react, svelte, etc.) | | --type | hello-world, hello-world-durable-object, scheduled, queues, openapi | | --category | hello-world, web-framework, demo, remote-template | | --template | Use external Git-hosted template | | --lang | ts, js, or python | | --deploy | Enable/disable automatic deployment (default: true) | | --git | Initialize Git repository (default: true) | | -y | Accept all defaults |

---

Wrangler CLI Reference

Authentication

# Login to Cloudflare (opens browser)
wrangler login

# Logout
wrangler logout

# Check current user
wrangler whoami

Development

# Start local dev server with hot reload
wrangler dev

# Dev with specific config
wrangler dev --config wrangler.staging.toml

# Dev on specific port
wrangler dev --port 3000

# Local mode (no Cloudflare connection)
wrangler dev --local

Deployment

# Deploy to Cloudflare
wrangler deploy

# Deploy to specific environment
wrangler deploy --env staging

# Deploy with dry run
wrangler deploy --dry-run

# Delete a Worker
wrangler delete

# Delete from specific environment
wrangler delete --env staging

Version Management

# Upload version without deploying
wrangler versions upload

# Deploy version with gradual rollout
wrangler versions deploy

# List deployments
wrangler deployments list

# View deployment status
wrangler deployments status

# Rollback to previous version
wrangler rollback

Monitoring & Logs

# Stream real-time logs
wrangler tail

# Filter by HTTP status
wrangler tail --status 500

# Filter by HTTP method
wrangler tail --method POST

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

# Sample rate (0-1)
wrangler tail --sampling-rate 0.1

KV Commands

# Create namespace
wrangler kv namespace create MY_KV

# List namespaces
wrangler kv namespace list

# Put a value
wrangler kv key put --binding=MY_KV "key" "value"

# Get a value
wrangler kv key get --binding=MY_KV "key"

# List keys
wrangler kv key list --binding=MY_KV

# Delete key
wrangler kv key delete --binding=MY_KV "key"

# Bulk operations (from JSON file)
wrangler kv bulk put --binding=MY_KV data.json
wrangler kv bulk delete --binding=MY_KV keys.json

R2 Storage Commands

# Create bucket
wrangler r2 bucket create my-bucket

# List buckets
wrangler r2 bucket list

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

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

# Delete object
wrangler r2 object delete my-bucket/path/file.txt

# Configure CORS
wrangler r2 bucket cors set my-bucket --rules='[{"origins":["*"]}]'

# Custom domain
wrangler r2 bucket domain add my-bucket my-cdn.example.com

D1 Database Commands

# Create database
wrangler d1 create my-database

# List databases
wrangler d1 list

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

# Execute from file
wrangler d1 execute my-database --file=./schema.sql

# Create migration
wrangler d1 migrations create my-database migration-name

# Apply migrations
wrangler d1 migrations apply my-database

# Time travel (point-in-time recovery)
wrangler d1 time-travel info my-database
wrangler d1 time-travel restore my-database --timestamp=2024-01-01T00:00:00Z

Secrets Management

# Add secret (interactive prompt)
wrangler secret put MY_SECRET

# Delete secret
wrangler secret delete MY_SECRET

# List secrets
wrangler secret list

# Bulk upload from file
wrangler secret bulk secrets.json

Queues Commands

# Create queue
wrangler queues create my-queue

# List queues
wrangler queues list

# Add consumer
wrangler queues consumer add my-queue my-worker

TypeScript Types

# Generate types from wrangler.toml bindings
wrangler types

# Include runtime types
wrangler types --include-runtime

Global Options

| Option | Description | |--------|-------------| | --config | Specify custom config file | | --env | Target specific environment | | --cwd | Run from different directory | | --env-file | Load environment variables from file | | --help | Show command help |

---

Configuration (wrangler.toml)

Basic Configuration

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-01-01"

# Enable workers.dev subdomain
workers_dev = true

# Account ID (or use CLOUDFLARE_ACCOUNT_ID env var)
account_id = "your-account-id"

Routes & Domains

# Single route
route = { pattern = "example.com/*", zone_name = "example.com" }

# Multiple routes
routes = [
  { pattern = "example.com/api/*", zone_name = "example.com" },
  { pattern = "api.example.com/*", zone_name = "example.com" }
]

# Custom domain
routes = [
  { pattern = "api.example.com", custom_domain = true }
]

KV Bindings

[[kv_namespaces]]
binding = "MY_KV"
id = "abc123..."

# Preview namespace (for wrangler dev)
[[kv_namespaces]]
binding = "MY_KV"
id = "abc123..."
preview_id = "def456..."

R2 Buckets

[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "my-bucket"

D1 Databases

[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "abc123..."

Durable Objects

[durable_objects]
bindings = [
  { name = "MY_DO", class_name = "MyDurableObject" }
]

[[migrations]]
tag = "v1"
new_classes = ["MyDurableObject"]

Queues

# Producer
[[queues.producers]]
binding = "MY_QUEUE"
queue = "my-queue"

# Consumer
[[queues.consumers]]
queue = "my-queue"
max_batch_size = 10
max_batch_timeout = 30

Environment Variables

[vars]
API_URL = "https://api.example.com"
DEBUG = "false"

Scheduled Triggers (Cron)

[triggers]
crons = [
  "0 * * * *",      # Every hour
  "0 0 * * *",      # Daily at midnight
  "*/5 * * * *"     # Every 5 minutes
]

Development Settings

[dev]
ip = "localhost"
port = 8787
local_protocol = "http"

Environment-Specific Configuration

# Staging environment
[env.staging]
name = "my-worker-staging"
vars = { DEBUG = "true" }

[env.staging.routes]
pattern = "staging.example.com/*"
zone_name = "example.com"

# Production environment
[env.production]
name = "my-worker-production"
vars = { DEBUG = "false" }

Resource Limits

[limits]
cpu_ms = 50

Observability

[observability]
enabled = true

[observability.logs]
enabled = true
invocation_logs = true
head_sampling_rate = 1

---

Miniflare (Local Development)

Miniflare is a local simulator for Cloudflare Workers using the workerd runtime.

Installation

npm install miniflare --save-dev

Programmatic Usage

import { Miniflare } from "miniflare";

const mf = new Miniflare({
  script: `
    export default {
      async fetch(request, env) {
        return new Response("Hello from Miniflare!");
      }
    }
  `,
  modules: true,
});

// Dispatch a request
const response = await mf.dispatchFetch("http://localhost/");
console.log(await response.text());

// Cleanup
await mf.dispose();

With Bindings

const mf = new Miniflare({
  scriptPath: "./src/index.ts",
  modules: true,
  kvNamespaces: ["MY_KV"],
  r2Buckets: ["MY_BUCKET"],
  d1Databases: ["DB"],
  durableObjects: {
    MY_DO: "MyDurableObject"
  },
  bindings: {
    API_KEY: "secret-key"
  }
});

// Access bindings
const bindings = await mf.getBindings();
await bindings.MY_KV.put("key", "value");

Persistence Options

const mf = new Miniflare({
  scriptPath: "./src/index.ts",
  modules: true,
  kvPersist: true,           // Persist to .mf/kv
  r2Persist: "./data/r2",    // Custom path
  d1Persist: true,
  cachePersist: true,
});

Multiple Workers

const mf = new Miniflare({
  workers: [
    {
      name: "api",
      scriptPath: "./api/index.ts",
      modules: true,
      routes: ["*/api/*"]
    },
    {
      name: "frontend",
      scriptPath: "./frontend/index.ts",
      modules: true,
      routes: ["*"]
    }
  ]
});

Debugging with Inspector

const mf = new Miniflare({
  scriptPath: "./src/index.ts",
  modules: true,
  inspectorPort: 9229,  // Connect Chrome DevTools
  verbose: true,        // Detailed logging
});

Core API Methods

| Method | Description | |--------|-------------| | dispatchFetch(url, init?) | Send HTTP request to worker | | getBindings() | Get all worker bindings | | getWorker(name?) | Get specific worker instance | | getCaches() | Get CacheStorage instance | | getD1Database(binding) | Get D1 database instance | | dispose() | Cleanup and shutdown |

---

Common Patterns

Basic Fetch Handler

export default {
  async fetch(request, env, ctx) {
    return new Response('Hello World!', {
      headers: { 'Content-Type': 'text/plain' }
    });
  }
};

JSON API Response

export default {
  async fetch(request, env, ctx) {
    const data = { message: 'Hello from Workers', timestamp: Date.now() };
    return new Response(JSON.stringify(data), {
      headers: { 'Content-Type': 'application/json' }
    });
  }
};

Router Pattern

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

    switch (url.pathname) {
      case '/api/users':
        return handleUsers(request, env);
      case '/api/posts':
        return handlePosts(request, env);
      default:
        return new Response('Not Found', { status: 404 });
    }
  }
};

Request Method Handling

export default {
  async fetch(request, env, ctx) {
    switch (request.method) {
      case 'GET':
        return handleGet(request, env);
      case 'POST':
        const body = await request.json();
        return handlePost(body, env);
      case 'PUT':
        return handlePut(request, env);
      case 'DELETE':
        return handleDelete(request, env);
      default:
        return new Response('Method Not Allowed', { status: 405 });
    }
  }
};

Workers KV Storage

export default {
  async fetch(request, env, ctx) {
    // Write to KV
    await env.MY_KV.put('key', 'value', { expirationTtl: 3600 });

    // Read from KV
    const value = await env.MY_KV.get('key');

    // Read as JSON
    const data = await env.MY_KV.get('data', { type: 'json' });

    // Delete from KV
    await env.MY_KV.delete('key');

    // List keys
    const list = await env.MY_KV.list({ prefix: 'user:' });

    return new Response(value);
  }
};

D1 Database

export default {
  async fetch(request, env, ctx) {
    // Query
    const { results } = await env.DB.prepare(
      "SELECT * FROM users WHERE id = ?"
    ).bind(1).all();

    // Insert
    await env.DB.prepare(
      "INSERT INTO users (name, email) VALUES (?, ?)"
    ).bind("John", "[email protected]").run();

    // Batch
    const batch = await env.DB.batch([
      env.DB.prepare("INSERT INTO users (name) VALUES (?)").bind("Alice"),
      env.DB.prepare("INSERT INTO users (name) VALUES (?)").bind("Bob"),
    ]);

    return Response.json(results);
  }
};

R2 Object Storage

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    const key = url.pathname.slice(1);

    switch (request.method) {
      case 'PUT':
        await env.MY_BUCKET.put(key, request.body, {
          httpMetadata: {
            contentType: request.headers.get('Content-Type')
          }
        });
        return new Response('Uploaded');

      case 'GET':
        const object = await env.MY_BUCKET.get(key);
        if (!object) return new Response('Not Found', { status: 404 });
        return new Response(object.body, {
          headers: { 'Content-Type': object.httpMetadata.contentType }
        });

      case 'DELETE':
        await env.MY_BUCKET.delete(key);
        return new Response('Deleted');
    }
  }
};

Durable Objects

// Worker entry point
export default {
  async fetch(request, env, ctx) {
    const id = env.COUNTER.idFromName('global');
    const stub = env.COUNTER.get(id);
    return stub.fetch(request);
  }
};

// Durable Object class
export class Counter {
  constructor(state, env) {
    this.state = state;
  }

  async fetch(request) {
    let count = (await this.state.storage.get('count')) || 0;

    if (request.method === 'POST') {
      count++;
      await this.state.storage.put('count', count);
    }

    return Response.json({ count });
  }
}

Queues Producer/Consumer

// Producer
export default {
  async fetch(request, env, ctx) {
    await env.MY_QUEUE.send({
      type: 'email',
      to: '[email protected]',
      subject: 'Hello'
    });
    return new Response('Queued');
  }
};

// Consumer
export default {
  async queue(batch, env, ctx) {
    for (const message of batch.messages) {
      console.log('Processing:', message.body);
      // Process message
      message.ack();
    }
  }
};

CORS Headers

const corsHeaders = {
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type, Authorization'
};

export default {
  async fetch(request, env, ctx) {
    if (request.method === 'OPTIONS') {
      return new Response(null, { headers: corsHeaders });
    }

    const response = await handleRequest(request, env);
    return new Response(response.body, {
      ...response,
      headers: { ...response.headers, ...corsHeaders }
    });
  }
};

Caching with Cache API

export default {
  async fetch(request, env, ctx) {
    const cache = caches.default;

    // Try cache first
    let response = await cache.match(request);

    if (!response) {
      // Cache miss - fetch from origin
      response = await fetch(request);

      // Cache for 1 hour
      response = new Response(response.body, response);
      response.headers.set('Cache-Control', 'max-age=3600');

      ctx.waitUntil(cache.put(request, response.clone()));
    }

    return response;
  }
};

Scheduled Events (Cron)

export default {
  async scheduled(event, env, ctx) {
    console.log('Cron executed at:', new Date(event.scheduledTime));

    // Perform background task
    await env.MY_KV.put('last_run', event.scheduledTime.toString());

    // Make external API call
    await fetch('https://api.example.com/webhook', {
      method: 'POST',
      body: JSON.stringify({ timestamp: event.scheduledTime })
    });
  }
};

Error Handling

export default {
  async fetch(request, env, ctx) {
    try {
      const data = await env.MY_KV.get('key');

      if (!data) {
        return Response.json(
          { error: 'Not Found' },
          { status: 404 }
        );
      }

      return Response.json({ data });

    } catch (error) {
      console.error('Worker error:', error);

      return Response.json(
        { error: 'Internal Server Error' },
        { status: 500 }
      );
    }
  }
};

Environment Variables & Secrets

export default {
  async fetch(request, env, ctx) {
    // Access variables from wrangler.toml [vars]
    const apiUrl = env.API_URL;

    // Access secrets (wrangler secret put)
    const apiKey = env.API_KEY;

    const response = await fetch(`${apiUrl}/data`, {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    });

    return response;
  }
};

---

TypeScript Support

Type Generation

# Generate types from wrangler.toml
wrangler types

# Output to custom file
wrangler types --outdir ./types

worker-configuration.d.ts

// Auto-generated by wrangler types
interface Env {
  MY_KV: KVNamespace;
  MY_BUCKET: R2Bucket;
  DB: D1Database;
  MY_DO: DurableObjectNamespace;
  API_KEY: string;
}

Typed Handler

export default {
  async fetch(
    request: Request,
    env: Env,
    ctx: ExecutionContext
  ): Promise<Response> {
    const value = await env.MY_KV.get('key');
    return new Response(value);
  }
};

---

Official Templates

Cloudflare provides production-ready templates at github.com/cloudflare/templates.

Using Templates

# Clone any template with C3
npm create cloudflare@latest my-app -- --template cloudflare/templates/<template-name>

# Examples
npm create cloudflare@latest my-db -- --template cloudflare/templates/d1-template
npm create cloudflare@latest my-chat -- --template cloudflare/templates/durable-chat-template
npm create cloudflare@latest my-ai -- --template cloudflare/templates/llm-chat-app-template

Full-Stack & Framework Templates

| Template | Description | |----------|-------------| | next-starter-template | Next.js starter application | | remix-starter-template | Remix framework starter | | astro-blog-starter-template | Blog platform using Astro | | vite-react-template | Vite with React configuration | | react-router-starter-template | React Router basic setup | | react-router-hono-fullstack-template | Full-stack React Router + Hono backend | | react-router-postgres-ssr-template | SSR with PostgreSQL integration | | react-postgres-fullstack-template | React frontend with PostgreSQL backend |

Data & Storage Templates

| Template | Description | |----------|-------------| | d1-template | D1 SQL database starter with migrations | | d1-starter-sessions-api-template | Session management using D1 | | to-do-list-kv-template | Key-Value storage demonstration | | postgres-hyperdrive-template | PostgreSQL via Hyperdrive connection pooling | | mysql-hyperdrive-template | MySQL via Hyperdrive | | r2-explorer-template | R2 object storage interface |

Real-Time & Durable Objects Templates

| Template | Description | |----------|-------------| | durable-chat-template | Real-time chat with WebSockets and PartyKit | | hello-world-do-template | Durable Objects introduction | | multiplayer-globe-template | Real-time collaborative mapping |

AI & LLM Templates

| Template | Description | |----------|-------------| | llm-chat-app-template | AI chatbot with Workers AI streaming | | text-to-image-template | Image generation with Workers AI |

Enterprise & SaaS Templates

| Template | Description | |----------|-------------| | saas-admin-template | SaaS dashboard with Astro, D1, and Workflows | | openauth-template | Authentication implementation | | workers-for-platforms-template | Platform-as-a-service architecture |

Advanced Patterns

| Template | Description | |----------|-------------| | workflows-starter-template | Workflow orchestration with Durable Objects | | microfrontend-template | Micro frontend architecture | | containers-template | Containerized deployment | | chanfana-openapi-template | OpenAPI documentation generation | | worker-publisher-template | Publishing service pattern |

Template Deep Dives

D1 Database Template

// Query D1 database
export default {
  async fetch(request, env) {
    const { results } = await env.DB.prepare(
      "SELECT * FROM comments LIMIT 3"
    ).all();

    return Response.json(results);
  }
};

Setup steps:

1. npm install
2. wrangler d1 create d1-template-database
3. Update wrangler.json with database ID
4. wrangler d1 migrations apply d1-template-database
5. wrangler deploy

Durable Chat Template (Real-Time)

Uses PartyKit Server API with Durable Objects:

// Chat room Durable Object
export class ChatRoom {
  connections = new Set();

  async onConnect(connection, ctx) {
    this.connections.add(connection);
    // Load chat history from SQL storage
    const history = await this.ctx.storage.sql.exec(
      "SELECT * FROM messages ORDER BY timestamp DESC LIMIT 50"
    );
    connection.send(JSON.stringify({ type: 'history', messages: history }));
  }

  async onMessage(message, connection) {
    // Store message
    await this.ctx.storage.sql.exec(
      "INSERT INTO messages (author, text, timestamp) VALUES (?, ?, ?)",
      [message.author, message.text, Date.now()]
    );
    // Broadcast to all connections
    for (const conn of this.connections) {
      conn.send(JSON.stringify(message));
    }
  }
}

LLM Chat App Template (Workers AI)

// Streaming AI responses with SSE
export default {
  async fetch(request, env) {
    if (request.method === 'POST' && new URL(request.url).pathname === '/api/chat') {
      const { messages } = await request.json();

      const stream = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
        messages: [
          { role: 'system', content: 'You are a helpful assistant.' },
          ...messages
        ],
        stream: true
      });

      return new Response(stream, {
        headers: { 'Content-Type': 'text/event-stream' }
      });
    }
  }
};

Customization points:

• MODEL_ID: Swap between Workers AI models
• SYSTEM_PROMPT: Adjust AI behavior
• Optional AI Gateway for rate limiting and analytics

Workflows Starter Template

// Define a workflow with steps
export class MyWorkflow extends WorkflowEntrypoint {
  async run(event, step) {
    // Step 1: Process input
    const processed = await step.do('process', async () => {
      return processData(event.payload);
    });

    // Step 2: Wait for time or event
    await step.sleep('wait', '1 hour');

    // Step 3: Continue processing
    const result = await step.do('finalize', async () => {
      return finalizeData(processed);
    });

    return result;
  }
}

Features:

• Time-based execution with delays
• Event-driven pauses
• Real-time status via WebSockets
• Durable state management

SaaS Admin Template

Stack: Astro + Shadcn UI + D1 + Workflows

// API with token authentication
export default {
  async fetch(request, env) {
    const token = request.headers.get('Authorization')?.replace('Bearer ', '');

    if (token !== env.API_TOKEN) {
      return Response.json({ error: 'Unauthorized' }, { status: 401 });
    }

    // Handle customer/subscription management
    const url = new URL(request.url);

    if (url.pathname === '/api/customers') {
      const customers = await env.DB.prepare(
        "SELECT * FROM customers"
      ).all();
      return Response.json(customers.results);
    }
  }
};

Features:

• Token-based authentication
• Customer management
• Subscription tracking
• Zod validation
• Background task processing with Workflows

---

Rust SDK (workers-rs)

The workers-rs crate provides ergonomic Rust bindings for building Cloudflare Workers compiled to WebAssembly.

Quick Start (Rust)

# Install prerequisites
rustup target add wasm32-unknown-unknown
cargo install cargo-generate

# Generate new Rust Worker project
cargo generate cloudflare/workers-rs

# Development
npx wrangler dev

# Deploy
npx wrangler deploy

Project Structure

my-rust-worker/
├── Cargo.toml          # Rust dependencies
├── wrangler.toml       # Wrangler configuration
└── src/
    └── lib.rs          # Worker entry point

Cargo.toml Configuration

[package]
name = "my-worker"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
worker = "0.4"
worker-macros = "0.4"
console_error_panic_hook = "0.1"

# Optional features
[dependencies.worker]
version = "0.4"
features = ["http", "d1", "queue"]

[profile.release]
opt-level = "s"      # Optimize for size
lto = true           # Link-time optimization
strip = true         # Strip symbols
codegen-units = 1    # Single codegen unit

Basic Fetch Handler

use worker::*;

#[event(fetch)]
async fn main(req: Request, env: Env, _ctx: Context) -> Result<Response> {
    Response::ok("Hello from Rust Worker!")
}

Router Pattern

use worker::*;

#[event(fetch)]
async fn main(req: Request, env: Env, _ctx: Context) -> Result<Response> {
    let router = Router::new();

    router
        .get("/", |_, _| Response::ok("Home"))
        .get_async("/users/:id", handle_user)
        .post_async("/users", create_user)
        .run(req, env)
        .await
}

async fn handle_user(req: Request, ctx: RouteContext<()>) -> Result<Response> {
    let id = ctx.param("id").unwrap();
    Response::ok(format!("User ID: {}", id))
}

async fn create_user(mut req: Request, ctx: RouteContext<()>) -> Result<Response> {
    let body: serde_json::Value = req.json().await?;
    Response::from_json(&body)
}

Request/Response Handling

use worker::*;

#[event(fetch)]
async fn main(mut req: Request, env: Env, _ctx: Context) -> Result<Response> {
    // Request info
    let method = req.method();
    let path = req.path();
    let url = req.url()?;

    // Headers
    let headers = req.headers();
    let auth = headers.get("Authorization")?.unwrap_or_default();

    // Query parameters
    let query: HashMap<String, String> = url.query_pairs().into_owned().collect();

    // Body parsing
    let json_body: serde_json::Value = req.json().await?;
    let text_body = req.text().await?;
    let bytes = req.bytes().await?;

    // Build response
    let mut headers = Headers::new();
    headers.set("Content-Type", "application/json")?;
    headers.set("X-Custom-Header", "value")?;

    Ok(Response::ok("Hello")?
        .with_headers(headers)
        .with_status(200))
}

JSON API

use serde::{Deserialize, Serialize};
use worker::*;

#[derive(Serialize, Deserialize)]
struct User {
    id: u32,
    name: String,
    email: String,
}

#[event(fetch)]
async fn main(mut req: Request, env: Env, _ctx: Context) -> Result<Response> {
    match req.method() {
        Method::Get => {
            let user = User {
                id: 1,
                name: "Alice".into(),
                email: "[email protected]".into(),
            };
            Response::from_json(&user)
        }
        Method::Post => {
            let user: User = req.json().await?;
            Response::from_json(&user)
        }
        _ => Response::error("Method not allowed", 405),
    }
}

KV Storage

use worker::*;

#[event(fetch)]
async fn main(req: Request, env: Env, _ctx: Context) -> Result<Response> {
    let kv = env.kv("MY_KV")?;

    // Put value
    kv.put("key", "value")?.execute().await?;

    // Put with expiration (seconds)
    kv.put("temp_key", "value")?
        .expiration_ttl(3600)
        .execute()
        .await?;

    // Put JSON
    let data = serde_json::json!({"foo": "bar"});
    kv.put("json_key", data)?.execute().await?;

    // Get value
    let value = kv.get("key").text().await?;

    // Get as JSON
    let json_value: Option<serde_json::Value> = kv.get("json_key").json().await?;

    // List keys
    let list = kv.list().prefix("user:").execute().await?;
    for key in list.keys {
        console_log!("Key: {}", key.name);
    }

    // Delete
    kv.delete("key").await?;

    Response::ok("KV operations complete")
}

Durable Objects

use worker::*;

// Define the Durable Object
#[durable_object]
pub struct Counter {
    state: State,
    env: Env,
}

#[durable_object]
impl DurableObject for Counter {
    fn new(state: State, env: Env) -> Self {
        Self { state, env }
    }

    async fn fetch(&mut self, req: Request) -> Result<Response> {
        // Get current count from storage
        let mut count: u64 = self.state.storage().get("count").await.unwrap_or(0);

        match req.method() {
            Method::Post => {
                count += 1;
                self.state.storage().put("count", count).await?;
            }
            Method::Delete => {
                count = 0;
                self.state.storage().put("count", count).await?;
            }
            _ => {}
        }

        Response::from_json(&serde_json::json!({ "count": count }))
    }
}

// Worker entry point
#[event(fetch)]
async fn main(req: Request, env: Env, _ctx: Context) -> Result<Response> {
    let namespace = env.durable_object("COUNTER")?;
    let id = namespace.id_from_name("global")?;
    let stub = id.get_stub()?;

    stub.fetch_with_request(req).await
}

wrangler.toml for Durable Objects:

[durable_objects]
bindings = [
  { name = "COUNTER", class_name = "Counter" }
]

[[migrations]]
tag = "v1"
new_classes = ["Counter"]

Durable Objects with SQLite Storage

#[durable_object]
impl DurableObject for MyObject {
    async fn fetch(&mut self, req: Request) -> Result<Response> {
        let sql = self.state.storage().sql();

        // Create table
        sql.exec(
            "CREATE TABLE IF NOT EXISTS items (id INTEGER PRIMARY KEY, name TEXT)",
            vec![],
        )?;

        // Insert
        sql.exec(
            "INSERT INTO items (name) VALUES (?)",
            vec![JsValue::from_str("item1")],
        )?;

        // Query
        let cursor = sql.exec("SELECT * FROM items", vec![])?;
        let rows: Vec<serde_json::Value> = cursor.to_array()?;

        Response::from_json(&rows)
    }
}

wrangler.toml for SQLite in Durable Objects:

[[migrations]]
tag = "v2"
new_sqlite_classes = ["MyObject"]

D1 Database

Enable with features = ["d1"]:

use worker::*;

#[derive(Deserialize, Serialize)]
struct User {
    id: i32,
    name: String,
    email: String,
}

#[event(fetch)]
async fn main(req: Request, env: Env, _ctx: Context) -> Result<Response> {
    let db = env.d1("DB")?;

    // Query all
    let stmt = db.prepare("SELECT * FROM users");
    let result = stmt.all().await?;
    let users: Vec<User> = result.results()?;

    // Query with parameters
    let stmt = db.prepare("SELECT * FROM users WHERE id = ?1");
    let user: Option<User> = stmt.bind(&[1.into()])?.first(None).await?;

    // Insert
    let stmt = db.prepare("INSERT INTO users (name, email) VALUES (?1, ?2)");
    stmt.bind(&["Alice".into(), "[email protected]".into()])?
        .run()
        .await?;

    // Batch operations
    let results = db.batch(vec![
        db.prepare("INSERT INTO users (name) VALUES (?1)").bind(&["Bob".into()])?,
        db.prepare("INSERT INTO users (name) VALUES (?1)").bind(&["Charlie".into()])?,
    ]).await?;

    Response::from_json(&users)
}

Queues

Enable with features = ["queue"]:

use worker::*;

#[derive(Serialize, Deserialize)]
struct Task {
    task_type: String,
    payload: String,
}

// Producer
#[event(fetch)]
async fn main(req: Request, env: Env, _ctx: Context) -> Result<Response> {
    let queue = env.queue("MY_QUEUE")?;

    let task = Task {
        task_type: "email".into(),
        payload: "[email protected]".into(),
    };

    queue.send(task).await?;

    Response::ok("Task queued")
}

// Consumer
#[event(queue)]
async fn queue_handler(batch: MessageBatch<Task>, env: Env, _ctx: Context) -> Result<()> {
    for message in batch.messages()? {
        let task = message.body();
        console_log!("Processing: {:?}", task.task_type);

        // Process the task...

        message.ack();  // Acknowledge successful processing
        // or message.retry(); // Retry later
    }

    // Or acknowledge all at once
    // batch.ack_all();

    Ok(())
}

wrangler.toml for Queues:

[[queues.producers]]
queue = "my-queue"
binding = "MY_QUEUE"

[[queues.consumers]]
queue = "my-queue"
max_batch_size = 10
max_batch_timeout = 30

R2 Object Storage

use worker::*;

#[event(fetch)]
async fn main(mut req: Request, env: Env, _ctx: Context) -> Result<Response> {
    let bucket = env.bucket("MY_BUCKET")?;
    let url = req.url()?;
    let key = url.path().trim_start_matches('/');

    match req.method() {
        Method::Put => {
            let body = req.bytes().await?;
            bucket.put(key, body)
                .http_metadata(HttpMetadata {
                    content_type: Some("application/octet-stream".into()),
                    ..Default::default()
                })
                .execute()
                .await?;
            Response::ok("Uploaded")
        }
        Method::Get => {
            match bucket.get(key).execute().await? {
                Some(object) => {
                    let body = object.body().unwrap().bytes().await?;
                    Ok(Response::from_bytes(body)?)
                }
                None => Response::error("Not found", 404),
            }
        }
        Method::Delete => {
            bucket.delete(key).await?;
            Response::ok("Deleted")
        }
        _ => Response::error("Method not allowed", 405),
    }
}

Scheduled Events (Cron)

use worker::*;

#[event(scheduled)]
async fn scheduled(_event: ScheduledEvent, env: Env, _ctx: ScheduleContext) -> Result<()> {
    console_log!("Cron job executed!");

    let kv = env.kv("MY_KV")?;
    kv.put("last_run", chrono::Utc::now().to_rfc3339())?
        .execute()
        .await?;

    Ok(())
}

// Can combine with fetch handler
#[event(fetch)]
async fn main(req: Request, env: Env, _ctx: Context) -> Result<Response> {
    Response::ok("Worker with scheduled event")
}

HTTP Feature (Standard http Crate Compatibility)

Enable with features = ["http"] for compatibility with Axum, Hyper, etc:

use worker::*;

#[event(fetch)]
async fn main(req: HttpRequest, env: Env, _ctx: Context) -> Result<HttpResponse> {
    // req is now http::Request<worker::Body>
    let method = req.method();
    let uri = req.uri();
    let headers = req.headers();

    // Build standard http response
    let response = http::Response::builder()
        .status(200)
        .header("Content-Type", "application/json")
        .body(worker::Body::from(r#"{"status":"ok"}"#))?;

    Ok(response)
}

Axum Integration

use axum::{routing::get, Router};
use tower_service::Service;
use worker::*;

fn router() -> Router {
    Router::new()
        .route("/", get(|| async { "Hello from Axum on Workers!" }))
        .route("/users/:id", get(get_user))
}

async fn get_user(axum::extract::Path(id): axum::extract::Path<String>) -> String {
    format!("User: {}", id)
}

#[event(fetch)]
async fn main(req: HttpRequest, env: Env, _ctx: Context) -> Result<HttpResponse> {
    Ok(router().call(req).await?)
}

Environment Variables & Secrets

use worker::*;

#[event(fetch)]
async fn main(req: Request, env: Env, _ctx: Context) -> Result<Response> {
    // Environment variables from wrangler.toml [vars]
    let api_url = env.var("API_URL")?.to_string();

    // Secrets (wrangler secret put)
    let api_key = env.secret("API_KEY")?.to_string();

    // Use in fetch
    let mut headers = Headers::new();
    headers.set("Authorization", &format!("Bearer {}", api_key))?;

    let mut init = RequestInit::new();
    init.with_headers(headers);

    let response = Fetch::Request(Request::new_with_init(&api_url, &init)?)
        .send()
        .await?;

    Ok(response)
}

Error Handling

use worker::*;

#[event(fetch)]
async fn main(req: Request, env: Env, _ctx: Context) -> Result<Response> {
    // Set up panic hook for better error messages
    console_error_panic_hook::set_once();

    match handle_request(req, env).await {
        Ok(response) => Ok(response),
        Err(e) => {
            console_error!("Error: {:?}", e);
            Response::error(format!("Internal error: {}", e), 500)
        }
    }
}

async fn handle_request(req: Request, env: Env) -> Result<Response> {
    let kv = env.kv("MY_KV")?;

    let value = kv.get("key").text().await?
        .ok_or_else(|| Error::from("Key not found"))?;

    Response::ok(value)
}

Form Data & File Uploads

use worker::*;

#[event(fetch)]
async fn main(mut req: Request, env: Env, _ctx: Context) -> Result<Response> {
    let form = req.form_data().await?;

    for (name, entry) in form.entries() {
        match entry {
            FormEntry::Field(value) => {
                console_log!("Field {}: {}", name, value);
            }
            FormEntry::File(file) => {
                console_log!("File {}: {} bytes", file.name(), file.size());
                let bytes = file.bytes().await?;
                // Process file...
            }
        }
    }

    Response::ok("Form processed")
}

WebSockets

use worker::*;

#[event(fetch)]
async fn main(req: Request, env: Env, _ctx: Context) -> Result<Response> {
    let upgrade = req.headers().get("Upgrade")?;

    if upgrade.as_deref() == Some("websocket") {
        let pair = WebSocketPair::new()?;
        let server = pair.server;
        let client = pair.client;

        server.accept()?;

        wasm_bindgen_futures::spawn_local(async move {
            let mut event_stream = server.events().unwrap();

            while let Some(event) = event_stream.next().await {
                match event.unwrap() {
                    WebsocketEvent::Message(msg) => {
                        if let Some(text) = msg.text() {
                            server.send_with_str(&format!("Echo: {}", text)).unwrap();
                        }
                    }
                    WebsocketEvent::Close(_) => break,
                }
            }
        });

        Response::from_websocket(client)
    } else {
        Response::ok("WebSocket endpoint")
    }
}

Testing Rust Workers with Miniflare

// test.mjs
import { Miniflare } from "miniflare";

const mf = new Miniflare({
  scriptPath: "./build/worker/shim.mjs",
  modules: true,
  modulesRules: [
    { type: "CompiledWasm", include: ["**/*.wasm"] }
  ],
  kvNamespaces: ["MY_KV"],
  d1Databases: ["DB"],
});

// Run tests
const response = await mf.dispatchFetch("http://localhost/api/users");
console.log(await response.json());

await mf.dispose();

Rust Worker Limitations

• No threading: Tokio/async_std not supported (no multi-threaded runtimes)
• WASM target: All dependencies must compile to wasm32-unknown-unknown
• Bundle size limits: Optimize with release profile settings
• Edition 2021+: Required for workers-rs v0.0.18+

Debugging Tips

use worker::*;

#[event(fetch)]
async fn main(req: Request, env: Env, _ctx: Context) -> Result<Response> {
    // Console logging
    console_log!("Request path: {}", req.path());
    console_error!("This is an error message");

    // Debug with serde_json
    console_log!("Request: {:?}", serde_json::to_string(&req.headers()));

    Response::ok("Debug complete")
}

---

workerd Runtime

workerd is the open-source JavaScript/WebAssembly runtime that powers Cloudflare Workers. It can be self-hosted for local development, testing, or running Workers outside Cloudflare's network.

What is workerd?

┌─────────────────────────────────────────────────────────┐
│                    workerd Runtime                       │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐ │
│  │     V8      │  │   WASM      │  │   Cap'n Proto   │ │
│  │  JavaScript │  │   Runtime   │  │  Configuration  │ │
│  │   Engine    │  │             │  │                 │ │
│  └──────┬──────┘  └──────┬──────┘  └────────┬────────┘ │
│         │                │                   │          │
│  ┌──────┴────────────────┴───────────────────┴────────┐ │
│  │              Service Mesh / Bindings                │ │
│  │    (KV, D1, R2, Queues, External Services, etc.)   │ │
│  └────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

Use Cases

| Use Case | Description | |----------|-------------| | Application Server | Self-host Workers in your own infrastructure | | Development Tool | Local testing with production-identical runtime | | HTTP Proxy | Programmable request interception and routing | | Edge Computing | Deploy Workers to your own edge locations |

Installation

# macOS (Homebrew)
brew install workerd

# From source (requires Bazel)
git clone https://github.com/cloudflare/workerd
cd workerd
bazel build //src/workerd/server:workerd

# Binary releases available for:
# - Linux x86-64, ARM64 (glibc 2.35+)
# - macOS x86-64, ARM64 (13.5+)
# - Windows x86-64

Configuration (Cap'n Proto)

workerd uses Cap'n Proto text format for configuration:

# workerd.capnp
using Workerd = import "/workerd/workerd.capnp";

const config :Workerd.Config = (
  services = [
    (name = "main", worker = .mainWorker),
  ],

  sockets = [
    (name = "http", address = "*:8080", http = (), service = "main"),
  ],
);

const mainWorker :Workerd.Worker = (
  modules = [
    (name = "worker", esModule = embed "worker.js"),
  ],
  compatibilityDate = "2024-01-01",
);

Running workerd

# Start with configuration file
workerd serve config.capnp

# With socket activation (systemd)
workerd serve config.capnp --socket-fd http=3

# Validate configuration
workerd validate config.capnp

# Compile configuration (for deployment)
workerd compile config.capnp > compiled.bin

Worker Configuration

const myWorker :Workerd.Worker = (
  # ES Modules (recommended)
  modules = [
    (name = "main", esModule = embed "src/index.js"),
    (name = "utils", esModule = embed "src/utils.js"),
  ],

  # Or Service Worker syntax
  # serviceWorkerScript = embed "worker.js",

  # Compatibility settings
  compatibilityDate = "2024-01-01",
  compatibilityFlags = ["nodejs_compat"],

  # Bindings
  bindings = [
    (name = "MY_KV", kvNamespace = "kv-namespace-id"),
    (name = "MY_VAR", text = "hello"),
    (name = "MY_SECRET", text = "secret-value"),
    (name = "BACKEND", service = "backend-service"),
  ],

  # Durable Objects
  durableObjectNamespaces = [
    (className = "Counter", uniqueKey = "counter-ns"),
  ],
  durableObjectStorage = (localDisk = "do-storage"),
);

Service Types

const config :Workerd.Config = (
  services = [
    # Worker service
    (name = "api", worker = .apiWorker),

    # External HTTP backend
    (name = "backend", external = (
      address = "backend.example.com:443",
      http = (style = host),
      tls = (certificateAuthority = embed "ca.pem"),
    )),

    # Network access
    (name = "internet", network = (
      allow = ["public"],
      deny = ["10.0.0.0/8", "192.168.0.0/16"],
    )),

    # Disk directory
    (name = "static", disk = (
      path = "./public",
      writable = false,
    )),
  ],
);

Socket Configuration

const config :Workerd.Config = (
  sockets = [
    # HTTP socket
    (
      name = "http",
      address = "*:8080",
      http = (),
      service = "main",
    ),

    # HTTPS socket with TLS
    (
      name = "https",
      address = "*:8443",
      http = (),
      service = "main",
      tls = (
        certificateChain = embed "cert.pem",
        privateKey = embed "key.pem",
      ),
    ),

    # Unix socket
    (
      name = "unix",
      address = "unix:/var/run/workerd.sock",
      http = (),
      service = "main",
    ),
  ],
);

Binding Types

bindings = [
  # Text/string binding
  (name = "API_URL", text = "https://api.example.com"),

  # JSON binding
  (name = "CONFIG", json = "{\"debug\": true}"),

  # Binary data
  (name = "WASM_MODULE", wasmModule = embed "module.wasm"),

  # Cryptographic key
  (name = "SIGNING_KEY", cryptoKey = (
    raw = embed "key.bin",
    algorithm = (name = "HMAC", hash = "SHA-256"),
    usages = ["sign", "verify"],
  )),

  # Service binding (inter-worker communication)
  (name = "AUTH_SERVICE", service = "auth"),

  # KV namespace
  (name = "CACHE", kvNamespace = "cache-ns-id"),

  # R2 bucket
  (name = "STORAGE", r2Bucket = "my-bucket"),

  # D1 database
  (name = "DB", d1Database = "database-id"),

  # Queue
  (name = "TASK_QUEUE", queue = "tasks"),

  # Analytics Engine
  (name = "ANALYTICS", analyticsEngine = "my-dataset"),
],

Durable Objects (Self-Hosted)

const myWorker :Workerd.Worker = (
  modules = [
    (name = "main", esModule = embed "worker.js"),
  ],

  # Define DO classes
  durableObjectNamespaces = [
    (className = "Counter", uniqueKey = "counter"),
    (className = "ChatRoom", uniqueKey = "chat"),
  ],

  # Local disk storage for DO state
  durableObjectStorage = (
    localDisk = "./do-data",
  ),

  compatibilityDate = "2024-01-01",
);

worker.js with Durable Object:

export class Counter {
  constructor(state, env) {
    this.state = state;
  }

  async fetch(request) {
    let count = (await this.state.storage.get("count")) || 0;
    count++;
    await this.state.storage.put("count", count);
    return new Response(JSON.stringify({ count }));
  }
}

export default {
  async fetch(request, env) {
    const id = env.COUNTER.idFromName("global");
    const stub = env.COUNTER.get(id);
    return stub.fetch(request);
  }
};

Network Configuration

# Allow outbound to public internet only
(name = "internet", network = (
  allow = ["public"],
)),

# Allow specific CIDRs
(name = "internal", network = (
  allow = ["10.0.0.0/8", "172.16.0.0/12"],
  deny = ["10.0.0.1/32"],  # Except this IP
)),

# Allow all (not recommended for production)
(name = "all", network = (
  allow = ["0.0.0.0/0", "::/0"],
)),

TLS Configuration

# Client TLS (for external services)
(name = "secure-backend", external = (
  address = "api.example.com:443",
  http = (),
  tls = (
    certificateAuthority = embed "ca-bundle.pem",
    minVersion = "TLSv1.3",
  ),
)),

# Server TLS (for sockets)
(
  name = "https",
  address = "*:443",
  http = (),
  service = "main",
  tls = (
    certificateChain = embed "fullchain.pem",
    privateKey = embed "privkey.pem",
    minVersion = "TLSv1.2",
    # OCSP stapling
    ocspResponse = embed "ocsp.der",
  ),
),

Using with Wrangler (Local Dev)

# Set workerd path for wrangler dev
export MINIFLARE_WORKERD_PATH="/usr/local/bin/workerd"

# Run local development
wrangler dev

# Or explicitly use local mode
wrangler dev --local

systemd Integration

# /etc/systemd/system/workerd.socket
[Unit]
Description=workerd HTTP Socket

[Socket]
ListenStream=80
ListenStream=443

[Install]
WantedBy=sockets.target

# /etc/systemd/system/workerd.service
[Unit]
Description=workerd Server
Requires=workerd.socket

[Service]
Type=simple
User=workerd
Group=workerd
ExecStart=/usr/local/bin/workerd serve /etc/workerd/config.capnp \
  --socket-fd http=3 --socket-fd https=4
Restart=on-failure

[Install]
WantedBy=multi-user.target

# Enable and start
sudo systemctl enable workerd.socket
sudo systemctl start workerd.socket

Docker Deployment

FROM ghcr.io/cloudflare/workerd:latest

COPY config.capnp /etc/workerd/
COPY src/ /app/src/

EXPOSE 8080

CMD ["serve", "/etc/workerd/config.capnp"]

# docker-compose.yml
services:
  workerd:
    image: ghcr.io/cloudflare/workerd:latest
    ports:
      - "8080:8080"
    volumes:
      - ./config.capnp:/etc/workerd/config.capnp:ro
      - ./src:/app/src:ro
      - ./do-data:/var/lib/workerd/do
    command: serve /etc/workerd/config.capnp

Compatibility Dates

workerd maintains backward compatibility through date-based versioning:

const myWorker :Workerd.Worker = (
  # Use APIs as they existed on this date
  compatibilityDate = "2024-01-01",

  # Enable specific compatibility flags
  compatibilityFlags = [
    "nodejs_compat",           # Node.js API compatibility
    "streams_enable_constructors",
    "transformstream_enable_standard_constructor",
  ],
);

Runtime APIs

workerd implements web-standard APIs:

| Category | APIs | |----------|------| | Fetch | fetch(), Request, Response, Headers | | Streams | ReadableStream, WritableStream, TransformStream | | Crypto | crypto.subtle, crypto.getRandomValues() | | Encoding | TextEncoder, TextDecoder, atob(), btoa() | | Timers | setTimeout(), setInterval(), scheduler.wait() | | URL | URL, URLSearchParams, URLPattern | | Cache | caches.default, caches.open() | | WebSocket | WebSocket, WebSocketPair | | Console | console.log(), console.error(), etc. |

Limitations (Self-Hosted)

• Single-threaded: One event loop per process; scale with multiple instances
• Durable Objects: Local disk only (no distributed storage)
• No hardened sandbox: Run in VM for untrusted code
• Feature parity: Some Cloudflare-specific features unavailable

Security Considerations

⚠️  workerd provides logical isolation but is NOT a security sandbox.

For untrusted code:
- Run inside a VM (firecracker, gVisor, etc.)
- Use container isolation (Docker with seccomp)
- Network namespace isolation
- Resource limits (cgroups)

---

Reference Files

This skill includes comprehensive documentation in references/:

• configuration.md - Detailed wrangler.toml reference
• getting_started.md - Setup and first Worker guide
• platform.md - Platform capabilities and limits
• runtime_apis.md - Web APIs and Workers-specific APIs

Use view to read specific reference files when detailed information is needed.

---

Resources

• Workers Documentation
• Wrangler CLI Reference
• Wrangler Configuration
• Workers Examples
• Workers SDK GitHub
• Official Templates
• Miniflare
• Workers AI Models
• workers-rs (Rust SDK)
• Rust Workers Guide
• workerd Runtime
• Runtime APIs Reference

---

Notes

• Enhanced from workers-sdk, templates, workers-rs, and workerd repositories
• Includes Wrangler CLI, Miniflare, C3 scaffolding, Rust SDK, workerd runtime, and official templates
• JavaScript/TypeScript examples use ES modules format (recommended)
• Rust examples use async/await with workers-rs macros
• workerd configuration uses Cap'n Proto text format
• wrangler.toml examples can also use wrangler.jsonc format
• Templates cover full-stack, databases, real-time, AI, and enterprise patterns
• Rust Workers compile to WASM and require wasm32-unknown-unknown target
• workerd can be self-hosted for local development or production deployment