cloudflare-workers

name	cloudflare-workers
title	Cloudflare Workers
category	Hosting & Deploy
description	Use to build and deploy edge functions/APIs with Wrangler, and bind KV, R2, and D1 storage to your Worker.
tags	["edge","serverless","workers","wrangler","kv","r2","d1"]
official_docs	https://developers.cloudflare.com/workers/
sources	["https://developers.cloudflare.com/workers/get-started/guide/"]
last_verified	2026-08-10T00:00:00.000Z

Cloudflare Workers — Skillship

Run code on Cloudflare's global edge network with near-zero cold starts. A Worker is a fetch handler; storage comes from bindings — KV (key-value), R2 (S3-like objects), D1 (SQLite).

🧭 When to use this skill

• Use when: you need a fast, globally-distributed API, proxy, or edge middleware.
• Use when: you want serverless with minimal cold starts and edge KV/object/SQL storage.
• Don't use for: long-running processes, big Node-native deps, or heavy CPU jobs (use a VM host).

⚡ Quickstart

1. Create a project (C3)

npm create cloudflare@latest -- my-worker
# choose: Hello World example → Worker only → JavaScript/TypeScript
cd my-worker

2. Develop locally

npx wrangler dev      # http://localhost:8787 ; first run opens browser to log in

3. Deploy

npx wrangler deploy   # publishes to <worker>.<subdomain>.workers.dev

The handler

export default {
  async fetch(request, env, ctx) {
    return new Response("Hello Worker!");
  },
};

env holds your bindings/secrets; ctx.waitUntil(promise) lets background work finish after the response.

🧩 Common recipes

Recipe: wrangler config with bindings (wrangler.jsonc)

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-01",
  "kv_namespaces": [{ "binding": "CACHE", "id": "<kv-namespace-id>" }],
  "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "my-bucket" }],
  "d1_databases": [{ "binding": "DB", "database_name": "app", "database_id": "<d1-id>" }],
      

Recipe: Use KV, R2, D1 from the handler

export default {
  async fetch(req, env) {
    await env.CACHE.put("k", "v", { expirationTtl: 60 });   // KV
    const obj = await env.BUCKET.get("file.png");           // R2
    const { results } = await env.DB.prepare(
      "SELECT * FROM users WHERE id = ?"                    // D1 (parameterized)
    ).bind(1).all();
    return Response.json({ results });
  },
};

Recipe: Secrets (encrypted, not in wrangler config)

npx wrangler secret put STRIPE_SECRET_KEY   # prompts for the value; access via env.STRIPE_SECRET_KEY

Recipe: Scheduled (cron) Worker

// wrangler.jsonc: "triggers": { "crons": ["0 * * * *"] }

export default {
  async scheduled(event, env, ctx) { /* runs on the cron schedule */ },
};

🚀 Ship to production

• Secrets set with wrangler secret put — never in wrangler.jsonc vars (those are public).
• compatibility_date pinned; bindings (KV/R2/D1) created and IDs referenced correctly.
• Custom domain/route configured (or accept the workers.dev subdomain).
• Background work wrapped in ctx.waitUntil() so it completes after the response.
• Stay within Workers CPU-time/size limits; avoid Node-only APIs unless nodejs_compat is enabled.
• For push-to-deploy, connect the repo to Workers Builds.

🔐 Security & secrets

• vars in wrangler.jsonc are plaintext/public config; real secrets go through wrangler secret put (encrypted) and are read from env.
• Always parameterize D1 SQL (.bind(...)) — never string-concatenate user input.
• Scope KV/R2/D1 bindings to only what the Worker needs.

🐛 Common errors & fixes

Symptom	Likely cause	Fix
env.X is undefined	Binding not declared in wrangler.jsonc	Add the kv_namespaces/r2_buckets/d1_databases entry
Background work didn't run	Promise not awaited before response	ctx.waitUntil(promise)
Node.js API not available	Using Node built-ins	Enable nodejs_compat flag or avoid the API
Secret visible in dashboard config	Put in vars	Move to wrangler secret put
523 errors on first workers.dev deploy	New subdomain warming up	Wait ~1 minute and retry

📚 Sources

• https://developers.cloudflare.com/workers/get-started/guide/