Core Concepts

Workers Runtime: V8 isolates (not Node.js) running on Cloudflare's edge network

Cold start: <1ms vs 100ms+ for containers
Web APIs only (no fs, process.env)
Each request is isolated and stateless

Basic Structure:

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

Request Handling

Request Object:

const url = new URL(request.url);
const method = request.method; // GET, POST, etc.
const headers = request.headers;
const body = await request.json(); // or .text()

// Query parameters
const userId = url.searchParams.get('userId'); // ?userId=123

Response Object:

// Simple text
return new Response('Hello');

// JSON with headers
return new Response(JSON.stringify({data: 'value'}), {
  status: 201,
  headers: { 'Content-Type': 'application/json' }
});

// Error response
return new Response(JSON.stringify({error: 'Bad request'}), {
  status: 400,
  headers: { 'Content-Type': 'application/json' }
});

Basic Routing

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

    if (path === '/api/users' && method === 'GET') {
      return new Response(JSON.stringify([{id: 1, name: 'Alice'}]), {
        headers: { 'Content-Type': 'application/json' }
      });
    }

    if (path === '/api/users' && method === 'POST') {
      const userData = await request.json();
      // Validation
      if (!userData.name) {
        return new Response(JSON.stringify({error: 'Name required'}), {
          status: 400,
          headers: { 'Content-Type': 'application/json' }
        });
      }
      // Process...
      return new Response(JSON.stringify({id: 123, ...userData}), {
        status: 201,
        headers: { 'Content-Type': 'application/json' }
      });
    }

    return new Response('Not Found', { status: 404 });
  }
}

Environment & Configuration

wrangler.toml:

name = "my-worker"
compatibility_date = "2024-01-01"

# Non-secret environment variables
[vars]
API_URL = "https://api.example.com"
DEBUG = "true"

Secrets (sensitive data):

# Set secrets via CLI
wrangler secret put API_KEY
wrangler secret put DATABASE_PASSWORD

Using in code:

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const apiKey = env.API_KEY; // secret
    const apiUrl = env.API_URL; // regular env var

    return new Response(`Using ${apiUrl}`);
  }
}

TypeScript setup:

# Generate types for your specific Worker config
pnpm wrangler types

Add to tsconfig.json:

{
  "compilerOptions": {
    "types": ["./worker-configuration.d.ts"]
  }
}

External API Calls

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    try {
      // Call external API
      const response = await fetch('https://api.example.com/data', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${env.API_TOKEN}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ query: 'example' })
      });

      if (!response.ok) {
        return new Response(JSON.stringify({error: 'External API failed'}), {
          status: 500,
          headers: { 'Content-Type': 'application/json' }
        });
      }

      const data = await response.json();

      // Transform and return
      return new Response(JSON.stringify({
        result: data.someField,
        timestamp: Date.now()
      }), {
        headers: { 'Content-Type': 'application/json' }
      });

    } catch (error) {
      return new Response(JSON.stringify({error: 'Request failed'}), {
        status: 500,
        headers: { 'Content-Type': 'application/json' }
      });
    }
  }
}

Caching

Cache API (like a persistent Map<string, Response>):

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const cache = caches.default; // or await caches.open('my-cache')
    const cacheKey = 'weather-london';

    // Try cache first
    const cachedResponse = await cache.match(cacheKey);
    if (cachedResponse) {
      return cachedResponse;
    }

    // Cache miss - fetch fresh data
    const freshResponse = await fetch(`https://api.weather.com?key=${env.API_KEY}`);
    const data = await freshResponse.json();

    const response = new Response(JSON.stringify(data), {
      headers: { 
        'Content-Type': 'application/json',
        'Cache-Control': 'max-age=300' // Browser caches for 5 min
      }
    });

    // Store in Cloudflare cache (background)
    ctx.waitUntil(cache.put(cacheKey, response.clone()));

    return response;
  }
}

Key concepts:

caches.default = global cache, caches.open('name') = named cache
response.clone() = needed because Response can only be read once
ctx.waitUntil() = keep Worker alive for background task, don't block response
Cache-Control header = browser caching, separate from caches API

Middleware Pattern

// Middleware functions return Response to stop, null to continue
async function corsMiddleware(request: Request): Promise<Response | null> {
  if (request.method === 'OPTIONS') {
    return new Response(null, {
      headers: {
        'Access-Control-Allow-Origin': '*',
        'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE',
        'Access-Control-Allow-Headers': 'Content-Type, Authorization'
      }
    });
  }
  return null;
}

async function authMiddleware(request: Request): Promise<Response | null> {
  const authHeader = request.headers.get('Authorization');
  if (!authHeader?.startsWith('Bearer ')) {
    return new Response(JSON.stringify({error: 'Unauthorized'}), {
      status: 401,
      headers: { 'Content-Type': 'application/json' }
    });
  }
  return null;
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    // Run middleware chain
    const middlewares = [corsMiddleware];
    for (const middleware of middlewares) {
      const response = await middleware(request);
      if (response) return response;
    }

    // Protected routes
    const url = new URL(request.url);
    if (url.pathname.startsWith('/api/protected/')) {
      const authResponse = await authMiddleware(request);
      if (authResponse) return authResponse;
    }

    // Your routes...
    return new Response('OK');
  }
}

Streaming Responses

For large datasets or real-time data:

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const stream = new ReadableStream({
      async start(controller) {
        for (let i = 0; i < 10000; i++) {
          // Each line is a separate JSON object
          const chunk = JSON.stringify({id: i, data: `Item ${i}`}) + '\n';
          controller.enqueue(new TextEncoder().encode(chunk));

          // Yield occasionally
          if (i % 100 === 0) {
            await new Promise(resolve => setTimeout(resolve, 0));
          }
        }
        controller.close();
      }
    });

    return new Response(stream, {
      headers: {
        'Content-Type': 'application/x-ndjson', // Newline-delimited JSON
        'Transfer-Encoding': 'chunked'
      }
    });
  }
}

Production Patterns

Error handling & logging:

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const startTime = Date.now();

    try {
      // Your logic...
      const response = new Response(JSON.stringify({success: true}), {
        headers: { 'Content-Type': 'application/json' }
      });

      // Success metrics
      console.log(`Success: ${request.method} ${new URL(request.url).pathname} - ${Date.now() - startTime}ms`);
      return response;

    } catch (error) {
      console.error(`Error: ${request.method} ${request.url}`, error);
      return new Response(JSON.stringify({error: 'Internal Server Error'}), {
        status: 500,
        headers: { 'Content-Type': 'application/json' }
      });
    }
  }
}

Simple rate limiting:

const rateLimits = new Map<string, {count: number; resetTime: number}>();

function isRateLimited(ip: string, limit: number, windowMs: number): boolean {
  const now = Date.now();
  const current = rateLimits.get(ip);

  // No data or window expired - reset
  if (!current || now > current.resetTime) {
    rateLimits.set(ip, {count: 1, resetTime: now + windowMs});
    return false;
  }

  // Hit limit
  if (current.count >= limit) {
    return true;
  }

  // Increment and allow
  current.count++;
  return false;
}

Key Reminders

Stateless: Variables don't persist between requests
Web APIs: Use fetch, Request, Response, URL - not Node.js APIs
Secrets vs Env Vars: Secrets via CLI, regular config in wrangler.toml
TypeScript: Run wrangler types after config changes
Caching: caches API for persistence, ctx.waitUntil() for background tasks
Rate Limiting: Implement your own, resets on each deployment (use KV for persistence)

Deployment

# Deploy to production
wrangler deploy

# Deploy to staging
wrangler deploy --env staging

# View logs
wrangler tail

Cloudflare Workers Reference Sheet

Comments

More from this blog

Become a cracked product engineer today

Bipedal, humanoid, and the words for creature shapes in games

Lerp and smoothstep, what they actually do

IK and FK, what they actually are

How to make your textures fast on the GPU

Core Concepts

Request Handling

Basic Routing

Environment & Configuration

External API Calls

Caching

Middleware Pattern

Streaming Responses

Production Patterns

Key Reminders

Deployment

Command Palette

Comments

More from this blog

Core Concepts

Request Handling

Basic Routing

Environment & Configuration

External API Calls

Caching

Middleware Pattern

Streaming Responses

Production Patterns

Key Reminders

Deployment