Your First Worker

Static sites are great, but sometimes you need server-side logic — an API endpoint, a redirect rule, or a dynamic response. Cloudflare Workers let you run JavaScript at the edge, close to your users, with zero server management. In this lesson you'll build and deploy a simple JSON API.

Prerequisites

You need two things before starting:

Verify Node is installed:

node --version
# v20.x or higher is ideal

Scaffold the project

Cloudflare provides a CLI scaffolding tool. Run this in your terminal:

npm create cloudflare@latest -- my-first-worker

When prompted, choose:

1. What would you like to start with? → Hello World example
2. Which template? → Worker only
3. Which language? → JavaScript

Then enter the project directory:

cd my-first-worker

Understand the code structure

Open src/index.js. You'll see something like this:

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

That's the entire Worker. Here's what each piece does:

Run locally

Start the local development server:

npx wrangler dev

Open http://localhost:8787 in your browser. You should see "Hello World!" — your Worker is running locally.

Build a multi-route API

A static "Hello World" isn't useful. Let's build a simple JSON API with multiple routes. Replace the contents of src/index.js with:

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    const path = url.pathname;

    // Route: JSON greeting
    if (path === "/api/hello") {
      const name = url.searchParams.get("name") || "world";
      return new Response(
        JSON.stringify({ greeting: `Hello, ${name}!` }),
        {
          headers: { "Content-Type": "application/json" },
        }
      );
    }

    // Route: Current time
    if (path === "/api/time") {
      return new Response(
        JSON.stringify({ utc: new Date().toISOString() }),
        {
          headers: { "Content-Type": "application/json" },
        }
      );
    }

    // Route: Welcome page
    if (path === "/") {
      return new Response(
        "Welcome to my first Worker! Try /api/hello or /api/time",
        {
          headers: { "Content-Type": "text/plain" },
        }
      );
    }

    // Fallback: 404
    return new Response(
      JSON.stringify({ error: "Not found" }),
      {
        status: 404,
        headers: { "Content-Type": "application/json" },
      }
    );
  },
};

Save the file and test each route in your browser (Wrangler should still be running):

Deploy to production

When you're happy with it locally, deploy to Cloudflare's network:

npx wrangler deploy

The first time, Wrangler will open a browser tab to authenticate your Cloudflare account. After that, you'll see output like:

Published my-first-worker (0.5 sec)
  https://my-first-worker.YOUR-SUBDOMAIN.workers.dev

That URL is live. Your API is now running on Cloudflare's global network — over 300 locations worldwide.

Free tier limits

Workers on the free plan are generous for learning and small projects:

What you built

In under 10 minutes you created a dynamic API endpoint that:

• Runs on Cloudflare's global edge network (low latency everywhere)
• Has automatic SSL and DDoS protection
• Costs nothing within the free tier
• Scales automatically — no servers to manage

Next lesson, we'll add persistent storage with KV so your Worker can remember things between requests.