name: cloudflare-workers
description: "Build serverless applications on Cloudflare Workers. Covers runtime APIs, handlers (fetch, scheduled, queue, email), bindings (KV, R2, D1, Durable Objects, Queues, AI, Vectorize), wrangler.toml configuration, local development with Miniflare, static assets, compatibility flags, testing with Vitest. Keywords: Cloudflare Workers, serverless, edge computing, Wrangler, fetch handler, scheduled handler, bindings, KV, R2, D1, Durable Objects, Workers AI, Miniflare, wrangler.toml, compatibility_date."

Cloudflare Workers

Serverless platform for building applications across Cloudflare's global network.

Quick Navigation

• Runtime & handlers → references/runtime.md
• Bindings overview → references/bindings.md
• Wrangler configuration → references/wrangler.md
• Local development → references/local-dev.md
• Static assets → references/assets.md
• Testing → references/testing.md

When to Use

• Building serverless APIs or full-stack applications
• Running edge functions with global distribution
• Connecting to Cloudflare storage (KV, R2, D1, Durable Objects)
• Running AI inference with Workers AI
• Configuring Wrangler CLI and wrangler.toml
• Setting up local development with Miniflare
• Testing Workers with Vitest

Module Worker (Recommended Syntax)

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    return new Response("Hello, World!");
  },
} satisfies ExportedHandler<Env>;

Handler Types

Bindings Overview

Access Cloudflare resources via env object.

Minimal Configuration

// wrangler.jsonc
{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-03-07",
  "compatibility_flags": ["nodejs_compat"],
  "observability": {
    "enabled": true,
    "head_sampling_rate": 1
  }
}

Essential Commands

# Development
npx wrangler dev              # Local dev (Miniflare)
npx wrangler dev --remote     # Remote dev (code on Cloudflare)

# Deployment
npx wrangler deploy           # Deploy to production
npx wrangler versions upload  # Upload without deploying
npx wrangler versions deploy  # Promote version

# Secrets
npx wrangler secret put KEY   # Add secret
npx wrangler secret list      # List secrets

# Types
npx wrangler types            # Generate TypeScript types

Compatibility Settings

# wrangler.toml
compatibility_date = "2025-03-07"
compatibility_flags = ["nodejs_compat"]

Key flags:

• nodejs_compat — Enable Node.js APIs
• nodejs_compat_v2 — Improved process implementation

Quick Recipes

Fetch Handler with Routing

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === "/api/hello") {
      return Response.json({ message: "Hello!" });
    }

    if (url.pathname.startsWith("/static/")) {
      return env.ASSETS.fetch(request);
    }

    return new Response("Not Found", { status: 404 });
  },
};

Scheduled Handler (Cron)

export default {
  async scheduled(controller: ScheduledController, env: Env, ctx: ExecutionContext) {
    ctx.waitUntil(doBackgroundWork(env));
  },
};

# wrangler.toml
[triggers]
crons = ["0 * * * *"]  # Every hour

Queue Consumer

export default {
  async queue(batch: MessageBatch, env: Env, ctx: ExecutionContext) {
    for (const message of batch.messages) {
      console.log(message.body);
      message.ack();
    }
  },
};

Critical Prohibitions

• Do NOT store secrets in wrangler.toml — use wrangler secret put
• Do NOT use remote: true for Durable Objects or Workflows — unsupported
• Do NOT expect Workers AI to work locally — always requires remote connection
• Do NOT omit compatibility_date — defaults to oldest date (2021-11-02)
• Do NOT use Service Worker syntax for new projects — use ES Modules
• Do NOT mix Service Worker and Module syntax in same project

Common Gotchas

Related Skills

• cloudflare-pages — Full-stack hosting with Git deployment
• cloudflare-d1 — D1 database operations
• cloudflare-r2 — R2 object storage
• cloudflare-kv — KV namespace operations
• cloudflare-durable-objects — Stateful coordination