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)

typescript

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

Handler Types

Handler	Trigger	Use Case
`fetch`	HTTP request	APIs, websites
`scheduled`	Cron trigger	Background jobs
`queue`	Queue message	Async processing
`email`	Email received	Email routing

Bindings Overview

Access Cloudflare resources via env object.

Binding	Type	Local Dev
KV	`KVNamespace`	✅ Simulated
R2	`R2Bucket`	✅ Simulated
D1	`D1Database`	✅ Simulated
Durable Objects	`DurableObjectNamespace`	✅ Simulated
Queues	`Queue`	✅ Simulated
Workers AI	`Ai`	❌ Remote only
Vectorize	`VectorizeIndex`	❌ Remote only
Browser Rendering	`Fetcher`	❌ Remote only
Hyperdrive	`Hyperdrive`	❌ Remote only
Static Assets	`Fetcher`	✅ Simulated
Service Binding	`Fetcher`	✅ Simulated

Minimal Configuration

jsonc

// 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

bash

# 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

toml

# 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

typescript

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)

typescript

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

toml

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

Queue Consumer

typescript

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

Issue	Solution
Local bindings empty	Add `--local` flag to Wrangler KV/R2/D1 commands
AI not working locally	Use `remote: true` in ai binding config
Node APIs unavailable	Add `nodejs_compat` to compatibility_flags
First deploy fails	Use `wrangler deploy`, not `versions upload` for first deploy

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