Cloudflare Workers: Build Serverless Tools for Free

Run code at the edge, in 200+ cities, without managing servers. And yes, the free tier is actually useful.


Introduction

Cloudflare Workers let you run JavaScript, TypeScript, Rust, or Python code on Cloudflare's global edge network — the same infrastructure that handles 20%+ of the internet's traffic. Instead of deploying to a single region and routing every request there, your code runs in data centers scattered across the globe, milliseconds away from your users.

The magic is simple: you write a small script, deploy it with a CLI tool called Wrangler, and it runs instantly on every request that hits your domain. No containers to manage. No "cold starts" that take 2 seconds to spin up. No server patching at 3 AM.

Cloudflare offers a generous free tier — 100,000 requests per day, 10ms of CPU time per request, and access to the full Workers ecosystem including KV storage, D1 databases, R2 object storage, and even AI inference. For side projects, prototypes, and small production tools, that's more than enough to get real work done without spending a dime.

This guide covers everything from your first "Hello World" to real-world patterns like API proxies, URL shorteners, and AI inference at the edge. Let's build something.


Free Tier: What's Actually Included

Before we write code, let's be honest about the limits so you know what you're working with.

Feature Free Tier
Requests/day 100,000
CPU time/request 10ms
Worker scripts 100
Memory 128MB
KV reads/day 100,000
D1 reads/day 5 million
R2 storage 10 GB
Workers AI requests 100,000/day

100,000 requests/day means roughly 3 million requests per month. That's not hobby-project territory — that's small-to-medium production app territory. A URL shortener, a lightweight API gateway, or an A/B testing service can comfortably live on the free tier.

The 10ms CPU limit is the real constraint. This is CPU time, not total request time. Waiting on a fetch to an external API doesn't count toward this limit. But heavy computation — JSON parsing, encryption, image manipulation — burns through it fast. Keep workers lean and delegate heavy lifting to services designed for it.


Setting Up Your First Worker

Install Wrangler

Cloudflare's CLI tool is called Wrangler. Install it globally via npm:

npm install -g wrangler

Authenticate with your Cloudflare account:

wrangler login

This opens a browser window, authorizes Wrangler, and saves credentials locally. You'll need a Cloudflare account, but you don't need a domain on Cloudflare to use Workers.

Hello World

Create a new project:

wrangler init my-first-worker
cd my-first-worker

Select "Yes" when it asks to create a TypeScript worker. Wrangler scaffolds a basic project with src/index.ts:

export interface Env {
  // Bindings go here (KV, D1, R2, etc.)
}

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

The fetch handler is the entry point for HTTP requests. Every worker must export a default object with a fetch method that returns a Response. The Env interface holds your bindings (databases, storage buckets, secrets), and ExecutionContext lets you schedule work after returning a response via ctx.waitUntil().

Test locally:

wrangler dev

Open http://localhost:8787 in your browser. You should see "Hello World!"

Deploy

One command pushes to production:

wrangler deploy

Your worker gets a URL like https://my-first-worker.your-account.workers.dev. Live on Cloudflare's edge network in under a minute.


Real-World Use Cases

1. API Proxy / Gateway

Need to add authentication, rate limiting, or logging to an existing API without touching the original service? Put a Worker in front.

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Add an API key check
    const apiKey = request.headers.get("X-API-Key");
    if (apiKey !== env.API_SECRET) {
      return new Response("Unauthorized", { status: 401 });
    }

    // Strip the original host header, forward the rest
    const url = new URL(request.url);
    const target = new URL(url.pathname + url.search, "https://api.upstream-service.com");

    const modified = new Request(target, request);
    modified.headers.delete("X-API-Key"); // don't leak our secret

    return fetch(modified);
  },
};

Add rate limiting with KV:

async function checkRateLimit(clientId: string, env: Env): Promise<boolean> {
  const key = `rate:${clientId}`;
  const current = parseInt((await env.RATE_LIMIT_KV.get(key)) || "0");

  if (current > 100) return false; // 100 requests per minute

  await env.RATE_LIMIT_KV.put(key, String(current + 1), { expirationTtl: 60 });
  return true;
}

2. URL Shortener

A minimal URL shortener using KV storage:

export interface Env {
  URLS: KVNamespace;
}

function generateSlug(): string {
  return Math.random().toString(36).substring(2, 8);
}

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

    // POST /create → store URL, return slug
    if (request.method === "POST" && url.pathname === "/create") {
      const { longUrl } = await request.json<{ longUrl: string }>();
      const slug = generateSlug();
      await env.URLS.put(slug, longUrl, { expirationTtl: 86400 * 30 }); // 30 days
      return Response.json({ shortUrl: `https://${url.host}/${slug}` });
    }

    // GET /:slug → redirect
    const slug = url.pathname.slice(1);
    const longUrl = await env.URLS.get(slug);
    if (longUrl) {
      return Response.redirect(longUrl, 301);
    }

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

Deploy this and you have a working URL shortener with global edge caching, zero cold starts, and 100k free requests per day. Not bad for 30 lines of code.

3. Image Optimization

Use Workers to resize, format-convert, or add watermarks to images on the fly. Combine with Cloudflare Images or R2 for storage:

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    const imageUrl = url.searchParams.get("url");
    const width = url.searchParams.get("w") || "800";

    if (!imageUrl) return new Response("Missing url param", { status: 400 });

    // Fetch original image
    const response = await fetch(imageUrl);
    if (!response.ok) return new Response("Failed to fetch image", { status: 502 });

    // Use Cloudflare's Image Resizing (available on paid plans)
    // Or process with a library like @cf-wasm/photon on free tier
    const image = await response.arrayBuffer();

    // Return with appropriate cache headers
    return new Response(image, {
      headers: {
        "Content-Type": response.headers.get("Content-Type") || "image/jpeg",
        "Cache-Control": "public, max-age=31536000",
      },
    });
  },
};

For actual image manipulation on the free tier, check out @cf-wasm/photon — a WebAssembly-based image processing library that runs inside Workers.

4. A/B Testing

Route users to different versions of your site based on a cookie or random assignment:

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    const cookie = request.headers.get("Cookie") || "";
    let variant = cookie.match(/variant=(\w)/)?.[1];

    if (!variant) {
      variant = Math.random() < 0.5 ? "a" : "b";
    }

    url.hostname = variant === "a" ? "origin-site.com" : "new-site.com";

    const response = await fetch(url.toString(), request);
    const modified = new Response(response.body, response);
    modified.headers.append("Set-Cookie", `variant=${variant}; Path=/; Max-Age=86400`);

    return modified;
  },
};

Track the results by logging the variant assignment to your analytics platform or a D1 database.

5. Geolocation Redirect

Cloudflare injects CF-IPCountry and other geolocation headers into every request. Use them to route users to localized content:

export default {
  async fetch(request: Request): Promise<Response> {
    const country = request.headers.get("CF-IPCountry") || "US";
    const url = new URL(request.url);

    const localizedHosts: Record<string, string> = {
      DE: "de.example.com",
      FR: "fr.example.com",
      JP: "jp.example.com",
    };

    url.hostname = localizedHosts[country] || "www.example.com";
    return fetch(url.toString(), request);
  },
};

No external geolocation API needed. It's already in the request headers, added by Cloudflare at the edge.


Workers + KV Storage

KV (Key-Value) is Cloudflare's global, eventually-consistent data store. It's perfect for configuration, feature flags, session data, and cached content.

Creating a KV Namespace

wrangler kv:namespace create "MY_KV"

Add the binding to your wrangler.toml:

[[kv_namespaces]]
binding = "MY_KV"
id = "your-namespace-id"

Basic Operations

export interface Env {
  MY_KV: KVNamespace;
}

// Write
await env.MY_KV.put("key", "value", { expirationTtl: 3600 }); // expires in 1 hour

// Read
const value = await env.MY_KV.get("key");

// Read with metadata
const result = await env.MY_KV.getWithMetadata("key");
console.log(result.value, result.metadata);

// List keys
const list = await env.MY_KV.list({ prefix: "user:", limit: 10 });

Important: KV is eventually consistent. Writes may take up to 60 seconds to propagate globally. For strongly consistent reads, use D1 instead.


Workers + D1 Database (SQLite at the Edge)

D1 is Cloudflare's serverless SQLite database. If you know SQL, you already know D1. It's perfect for relational data, user accounts, content management, and anything that needs ACID transactions.

Setting Up D1

Create a database:

wrangler d1 create my-database

Add to wrangler.toml:

[[d1_databases]]
binding = "DB"
database_name = "my-database"
database_id = "your-database-id"

Running Migrations

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

Example schema:

CREATE TABLE users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  email TEXT UNIQUE NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Querying from a Worker

export interface Env {
  DB: D1Database;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Insert a user
    await env.DB.prepare("INSERT INTO users (email) VALUES (?)")
      .bind("user@example.com")
      .run();

    // Fetch users
    const { results } = await env.DB.prepare("SELECT * FROM users LIMIT 10").all();

    return Response.json(results);
  },
};

D1 supports parameterized queries, transactions, and even batch operations. It's SQLite, so full-text search, JSON functions, and window functions all work.


Workers + R2 Storage (S3-Compatible)

R2 is Cloudflare's object storage service. It's S3-compatible but with zero egress fees — you only pay for storage and operations, not for bandwidth. This makes it dramatically cheaper than AWS S3 for serving files to users.

Uploading Files

export interface Env {
  MY_BUCKET: R2Bucket;
}

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

    if (request.method === "PUT") {
      const key = url.pathname.slice(1);
      await env.MY_BUCKET.put(key, request.body);
      return new Response("Uploaded", { status: 201 });
    }

    if (request.method === "GET") {
      const key = url.pathname.slice(1);
      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 || "application/octet-stream",
        },
      });
    }

    return new Response("Method not allowed", { status: 405 });
  },
};

R2 is ideal for user uploads, backups, static assets, and media storage. Combined with Workers, you can build entire content pipelines — upload, process, serve — without touching a traditional server.


Workers AI: ML at the Edge

Cloudflare Workers AI lets you run machine learning models directly on the edge. No API keys for OpenAI, no network latency to external services. The model runs in the same data center handling your request.

Available Models

Workers AI includes models for:

Using Workers AI

export interface Env {
  AI: Ai;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const { prompt } = await request.json<{ prompt: string }>();

    const response = await env.AI.run("@cf/meta/llama-2-7b-chat-int8", {
      messages: [
        { role: "system", content: "You are a helpful assistant." },
        { role: "user", content: prompt },
      ],
    });

    return Response.json(response);
  },
};

Free tier includes 100,000 AI requests per day. That's enough to experiment heavily or run a small production AI feature without paying for external APIs.

Note: The free tier has limits on model sizes and concurrent requests. For heavy AI workloads, the paid tier scales better.


Comparison with Alternatives

Feature Cloudflare Workers Vercel Edge Deno Deploy Fly.io
Free requests 100K/day 1M/month (Vercel) 1M/month None (credits)
Cold starts None None None ~300ms
Languages JS/TS, Rust, Python JS/TS JS/TS, Python Anything (Docker)
Edge locations 300+ 100+ 35 30+
Built-in storage KV, D1, R2 Vercel KV, Postgres Deno KV Postgres, S3
Egress fees $0 (R2) $0 (Vercel) $0 $0
WASM support Yes Limited Yes Yes

Vercel Edge is great if you're already in the Next.js ecosystem. The integration is seamless. But you're locked into their platform conventions.

Deno Deploy offers a cleaner runtime (no Node.js baggage) and built-in TypeScript. The ecosystem is smaller but growing fast.

Fly.io gives you full Docker containers running globally. More flexibility, more complexity, and cold starts exist. Best for stateful services or when you need a full Linux environment.

Cloudflare Workers wins on edge coverage, integration breadth (KV/D1/R2/AI all under one roof), and the sheer generosity of the free tier.


Pricing Breakdown

Free Tier

Paid Tier (Workers Paid)

For context: a site doing 1 million requests per month costs about $0.30 on Workers. The free tier handles 3 million requests per month. Unless you're running a high-traffic production service, you may never need to pay.


Limitations and Workarounds

10ms CPU Time

The free tier's 10ms CPU limit is the biggest constraint. Strategies to work within it:

No Native WebSocket Server

Workers can receive WebSocket connections via Durable Objects, but free tier has limited Durable Object usage. For real-time features, consider:

Environment Differences

The Workers runtime is not Node.js. Some npm packages won't work because they depend on Node APIs like fs, crypto (legacy), or http. Solutions:

Cold Starts Don't Exist, But...

Workers don't have cold starts in the traditional sense. However, if you import massive dependencies or initialize large data structures at the top level, the script initialization can add latency. Keep top-level code minimal and lazy-load heavy modules inside the fetch handler.


Conclusion

Cloudflare Workers represents a genuinely useful free tier in a space where "free" often means "useless demo." 100,000 requests per day with edge deployment, KV storage, SQLite databases, object storage, and AI inference is enough to build and run real tools.

The patterns covered here — API proxies, URL shorteners, image optimization, A/B testing, geolocation routing, and AI features — are just scratching the surface. Combined with R2's zero-egress object storage and D1's familiar SQLite interface, you can build full-stack applications that scale globally without managing servers or sweating the bill.

If you've been on the fence about serverless because of cost or complexity, Workers is the place to start. Write the code, run wrangler deploy, and your tool is live in 200+ cities worldwide.


Further Reading


Built something cool with Workers? The devhandbook.io community wants to hear about it.