Cloudflare Workers Tutorial for Beginners: Build Your First API in 10 Minutes

What is Cloudflare Workers? (30-Second Explanation)

Cloudflare Workers lets you run JavaScript code on Cloudflare's global network—in 330+ cities worldwide. When someone in Tokyo requests your API, the code runs in Tokyo. Someone in São Paulo? It runs in São Paulo.

If you've used Express.js, AWS Lambda, or Vercel Edge Functions, you'll feel right at home. The concepts transfer directly.

💡 Real Talk: Teams regularly report reducing API latency from 180ms to under 15ms just by moving from regional cloud to Workers. The code change takes hours. The performance improvement is permanent.

Prerequisites

You'll need:

• Node.js 18+ — Download here
• A Cloudflare account — Sign up free (no credit card required)
• Basic JavaScript knowledge — If you can write a function, you're ready
• A code editor — VS Code recommended

Check your Node.js version:

1Install Wrangler CLI

Wrangler is Cloudflare's command-line tool for Workers development. Think of it like create-react-app but for serverless APIs.

Verify installation:

2Authenticate with Cloudflare

Connect Wrangler to your Cloudflare account:

This opens your browser. Click "Allow" to authorize Wrangler. You'll see:

Your credentials are stored locally. You only need to do this once per machine.

3Create Your First Worker

Let's create a new project:

When prompted:

• What type of application? → Select "Hello World" Worker
• TypeScript or JavaScript? → Choose TypeScript (recommended) or JavaScript
• Use git? → Yes (recommended)
• Deploy now? → No (we'll explore the code first)

Navigate into your project:

Your project structure:

my-first-worker/
├── src/
│   └── index.ts       ← Your Worker code lives here
├── wrangler.toml      ← Configuration file
├── package.json
└── tsconfig.json

4Understanding the Code

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

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

Let's break this down:

If you've used Express.js, this is similar to:

// Express equivalent
app.get('*', (req, res) => {
  res.send('Hello World!');
});

The difference? Workers use the standard Web APIs (Request, Response, fetch) that work in browsers. No Express-specific knowledge needed.

5Build a Real API

Let's build something useful: a simple REST API with multiple routes.

Replace your src/index.ts with:

interface Env {
  // Add your bindings here (KV, D1, R2, etc.)
}

// Simple in-memory data (use D1 for real apps)
const users = [
  { id: 1, name: 'Alice', city: 'London' },
  { id: 2, name: 'Bob', city: 'Tokyo' },
  { id: 3, name: 'Carlos', city: 'São Paulo' },
];

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const url = new URL(request.url);
    const path = url.pathname;
    
    // CORS headers for browser requests
    const headers = {
      'Content-Type': 'application/json',
      'Access-Control-Allow-Origin': '*',
    };
    
    // Route: GET /
    if (path === '/' && request.method === 'GET') {
      return new Response(JSON.stringify({
        message: 'Welcome to my API!',
        endpoints: ['/users', '/users/:id', '/health'],
        location: request.cf?.city || 'Unknown',
      }), { headers });
    }
    
    // Route: GET /users
    if (path === '/users' && request.method === 'GET') {
      return new Response(JSON.stringify(users), { headers });
    }
    
    // Route: GET /users/:id
    if (path.startsWith('/users/') && request.method === 'GET') {
      const id = parseInt(path.split('/')[2]);
      const user = users.find(u => u.id === id);
      
      if (!user) {
        return new Response(JSON.stringify({ error: 'User not found' }), {
          status: 404,
          headers,
        });
      }
      
      return new Response(JSON.stringify(user), { headers });
    }
    
    // Route: GET /health
    if (path === '/health') {
      return new Response(JSON.stringify({
        status: 'healthy',
        timestamp: new Date().toISOString(),
        edge_location: request.cf?.colo || 'Unknown',
      }), { headers });
    }
    
    // 404 for unknown routes
    return new Response(JSON.stringify({ error: 'Not found' }), {
      status: 404,
      headers,
    });
  },
};

6Test Locally

Start the local development server:

You'll see:

Now test your endpoints:

Hot reload is automatic. Edit your code, save, and the changes appear instantly. No restart needed.

7Deploy to Production

Ready to go live? One command:

Output:

That's it. Your API is now live on Cloudflare's global network. Try it from your phone, share the URL with a friend in another country—it works everywhere, instantly.

What's Next? Level Up Your Worker

You've built a basic API. Here's how to add real functionality:

wrangler d1 create my-database

const result = await env.AI.run('@cf/meta/llama-2-7b', { prompt: '...' });

wrangler r2 bucket create my-bucket

5 Common Mistakes to Avoid

Frequently Asked Questions