Cloudflare Workers basics

What a Worker is

A Cloudflare Worker is a small piece of serverless JavaScript that runs on Cloudflare's edge network, in front of your origin, when a request matches it. Instead of a dedicated server or a function in your hosting account, the code executes on the closest point of the Cloudflare network to your visitor, and returns the response you write.

The shape is a fetch handler: it receives a request, inspects the URL, headers and method, and either forwards to the origin, rewrites the request, returns content directly, or redirects. Because it runs before the origin is even contacted, a Worker can add a header, block a path, splice tiny HTML, or serve a config value without any server-side change.

Free plan limits, the practical picture

The Workers free plan is generous for small jobs but has hard ceilings. As of the current documentation these are the ones that usually bite:

The CPU number is active CPU, not wall time. Network I/O (waiting on fetch, KV or D1) does not count against the 10 ms, but JSON parsing and crypto do, so a free worker that parses a large payload or runs heavy logic can exhaust its budget quickly. Hitting the daily request ceiling returns error 1027; the billing resets at midnight UTC.

A small site's realistic free-tier niches are simple rewrites, A/B headers, geolocation redirects, and edge-response caching. Anything doing database work, heavy auth, or large data transformations usually needs the paid tier, or a different design.

What a Worker is not for

Workers invite a "can we make this an edge function?" instinct. Keep in mind what they cannot do well:

• Not a database host. Real joins, user accounts and long-running jobs need your origin or a D1/KV store with explicit design.
• Not a caching substitute. Workers run on every request they match. If your job is "cache more", the cache rules tuning route is the right place to look, not a Worker.
• Not a middleware free-for-all. Each Worker is small by design; the edge model rewards narrow transforms, not a web framework.
• Not a DDoS shield. Edge rate limiting and WAF exist for that; a Worker does not add block-level protection, the rate limiting tool is built for it.

Three honest Worker patterns

1. Add a security header

export default {
  async fetch(request) {
    const response = await fetch(request);
    const headers = new Headers(response.headers);
    headers.set("X-Content-Type-Options", "nosniff");
    return new Response(response.body, { status: response.status, headers });
  },
};

2. Redirect a legacy path

export default {
  async fetch(request) {
    const url = new URL(request.url);
    if (url.pathname === "/old") return Response.redirect("https://www.example.com/new", 301);
    return fetch(request);
  },
};

3. Set a variant cookie

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    const cookie = request.headers.get("cookie") || "";
    const requested = url.searchParams.get("variant");
    if (requested && !cookie.includes("variant=")) {
      const response = await fetch(request);
      const headers = new Headers(response.headers);
      headers.set("Set-Cookie", `variant=${requested}; Path=/; Max-Age=86400`);
      return new Response(response.body, { status: response.status, headers });
    }
    return fetch(request);
  },
};

When a Worker genuinely helps a small site

Workers earn their place for a handful of small, well-scoped edge jobs: injecting a header without touching shared hosting, serving a maintenance override from a config value, geoblocking a single toxic path in a few lines, or inserting a custom error page for the user-facing error page pattern. For everything else, prefer the platform primitives Cloudflare already bundles, and see the rate limiting guide for what the edge policy can do without any code.