Cloudflare Workers Complete Guide: Edge Computing from Setup to Production

User request → A server in one data center → Process → Respond

User request → Nearest edge node (300+ worldwide) → Process → Respond

# Global install
npm install -g wrangler

# Or use npx (recommended — no global install needed)
npx wrangler --version

npx wrangler login

# Scaffold a new project
npm create cloudflare@latest -- my-first-worker

# Follow the prompts:
# - Select "Hello World" example
# - Choose "Worker only"
# - Pick JavaScript or TypeScript
# - Enable git: Yes
# - Deploy now: No (test locally first)

my-first-worker/
├── src/
│   └── index.js      # Worker source code
├── wrangler.toml     # Configuration (or wrangler.jsonc)
├── package.json
└── node_modules/

name = "my-first-worker"           # Worker name and URL path
main = "src/index.js"              # Entry file
compatibility_date = "2024-01-01"  # Compatibility date

# Optional: bind KV storage
# [[kv_namespaces]]
# binding = "MY_KV"
# id = "xxxxxxxx"

# Optional: bind D1 database
# [[d1_databases]]
# binding = "DB"
# database_name = "my-db"
# database_id = "xxxxxxxx"

# Optional: environment variables
# [vars]
# API_KEY = "your-api-key"

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

cd my-first-worker
npx wrangler dev

⎔ Starting local server...
[wrangler] Ready on http://localhost:8787

npx wrangler deploy

Uploaded my-first-worker (1.23 sec)
Published my-first-worker (0.45 sec)
  https://my-first-worker.your-subdomain.workers.dev

export default {
  async fetch(request, env, ctx) {
    // Parse the request
    const url = new URL(request.url);
    const method = request.method;           // GET, POST, etc.
    const path = url.pathname;               // /api/users
    const params = url.searchParams;         // ?id=123
    const headers = request.headers;

    // Read POST body
    if (method === 'POST') {
      const body = await request.json();     // JSON
      // or await request.text()             // Plain text
      // or await request.formData()         // Form data
    }

    // Client metadata (Cloudflare-specific)
    const ip = request.headers.get('CF-Connecting-IP');
    const country = request.cf?.country;     // Country code
    const city = request.cf?.city;

    return new Response('OK');
  },
};

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

// JSON
return new Response(JSON.stringify({ message: 'OK' }), {
  headers: { 'Content-Type': 'application/json' },
});

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

// Redirect
return Response.redirect('https://example.com', 302);

// Response with CORS headers
return new Response(data, {
  headers: {
    'Content-Type': 'application/json',
    'Access-Control-Allow-Origin': '*',
    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
  },
});

export default {
  async fetch(request, env, ctx) {
    // Proxy a request to another service
    const response = await fetch('https://api.example.com/data', {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer ' + env.API_KEY,
      },
    });

    return response;
  },
};

npx wrangler kv:namespace create "MY_CACHE"

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

export default {
  async fetch(request, env, ctx) {
    // Write
    await env.MY_CACHE.put('key', 'value');

    // Read
    const value = await env.MY_CACHE.get('key');

    // Delete
    await env.MY_CACHE.delete('key');

    // Write with TTL (in seconds)
    await env.MY_CACHE.put('session', 'data', { expirationTtl: 3600 });

    return new Response(value);
  },
};

npx wrangler d1 create my-database

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

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

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

export default {
  async fetch(request, env, ctx) {
    // Query all users
    const { results } = await env.DB.prepare(
      'SELECT * FROM users'
    ).all();

    // Parameterized query (prevents SQL injection)
    const user = await env.DB.prepare(
      'SELECT * FROM users WHERE id = ?'
    ).bind(1).first();

    // Insert a row
    await env.DB.prepare(
      'INSERT INTO users (name, email) VALUES (?, ?)'
    ).bind('Jane Doe', '[email protected]').run();

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

// src/index.js

// Target API host
const TARGET_HOST = 'api.openai.com';

// Allowed path prefixes (security measure)
const ALLOWED_PATHS = ['/v1/chat', '/v1/models', '/v1/embeddings'];

export default {
  async fetch(request, env, ctx) {
    // Handle CORS preflight
    if (request.method === 'OPTIONS') {
      return new Response(null, {
        headers: {
          'Access-Control-Allow-Origin': '*',
          'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
          'Access-Control-Allow-Headers': '*',
          'Access-Control-Max-Age': '86400',
        },
      });
    }

    const url = new URL(request.url);
    const path = url.pathname;

    // Only proxy allowed paths
    const isAllowed = ALLOWED_PATHS.some(p => path.startsWith(p));
    if (!isAllowed) {
      return new Response(JSON.stringify({ error: 'Path not allowed' }), {
        status: 403,
        headers: { 'Content-Type': 'application/json' },
      });
    }

    // Build the proxied request
    const targetUrl = `https://${TARGET_HOST}${path}${url.search}`;

    // Clone headers and strip Cloudflare-specific ones
    const headers = new Headers(request.headers);
    headers.delete('host');
    headers.delete('cf-connecting-ip');
    headers.delete('cf-ipcountry');

    // Forward the request
    const response = await fetch(targetUrl, {
      method: request.method,
      headers: headers,
      body: request.body,
    });

    // Add CORS headers to the response
    const newResponse = new Response(response.body, response);
    newResponse.headers.set('Access-Control-Allow-Origin', '*');

    return newResponse;
  },
};

https://api.openai.com/v1/chat/completions

https://your-worker.your-subdomain.workers.dev/v1/chat/completions

// src/index.js

// Generate a random short code
function generateCode(length = 6) {
  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
  let result = '';
  for (let i = 0; i < length; i++) {
    result += chars.charAt(Math.floor(Math.random() * chars.length));
  }
  return result;
}

// Validate URL format
function isValidUrl(string) {
  try {
    new URL(string);
    return true;
  } catch (_) {
    return false;
  }
}

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

    // Handle CORS preflight
    if (request.method === 'OPTIONS') {
      return new Response(null, {
        headers: {
          'Access-Control-Allow-Origin': '*',
          'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
          'Access-Control-Allow-Headers': 'Content-Type',
        },
      });
    }

    // Create a short link: POST /create
    if (path === '/create' && request.method === 'POST') {
      try {
        const { url: targetUrl } = await request.json();

        if (!targetUrl || !isValidUrl(targetUrl)) {
          return Response.json({ error: 'Invalid URL' }, { status: 400 });
        }

        // Generate a unique code
        let code = generateCode();
        let existing = await env.LINKS.get(code);
        while (existing) {
          code = generateCode();
          existing = await env.LINKS.get(code);
        }

        // Store the mapping (expires in 90 days)
        await env.LINKS.put(code, targetUrl, { expirationTtl: 90 * 24 * 60 * 60 });

        const shortUrl = `${url.origin}/${code}`;
        return Response.json({
          shortUrl,
          code,
          originalUrl: targetUrl
        }, {
          headers: { 'Access-Control-Allow-Origin': '*' },
        });
      } catch (e) {
        return Response.json({ error: 'Invalid request' }, { status: 400 });
      }
    }

    // Redirect: GET /:code
    if (path.length > 1 && request.method === 'GET') {
      const code = path.slice(1);
      const targetUrl = await env.LINKS.get(code);

      if (targetUrl) {
        return Response.redirect(targetUrl, 302);
      } else {
        return new Response('Short link not found', { status: 404 });
      }
    }

    // Landing page
    return new Response(`
      <h1>URL Shortener</h1>
      <p>POST /create with {"url": "https://example.com"}</p>
    `, {
      headers: { 'Content-Type': 'text/html' },
    });
  },
};

name = "url-shortener"
main = "src/index.js"
compatibility_date = "2024-01-01"

[[kv_namespaces]]
binding = "LINKS"
id = "your-kv-namespace-id"

curl -X POST https://your-worker.workers.dev/create \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.example.com/very-long-path"}'

{
  "shortUrl": "https://your-worker.workers.dev/abc123",
  "code": "abc123",
  "originalUrl": "https://www.example.com/very-long-path"
}

npm create hono@latest my-api
# Select the cloudflare-workers template
cd my-api
npm install

// src/index.js
import { Hono } from 'hono';
import { cors } from 'hono/cors';

const app = new Hono();

// Global middleware
app.use('*', cors());

// Routes
app.get('/', (c) => c.text('Hello Hono!'));

app.get('/users/:id', (c) => {
  const id = c.req.param('id');
  return c.json({ id, name: 'User ' + id });
});

app.post('/users', async (c) => {
  const body = await c.req.json();
  return c.json({ created: true, data: body });
});

// 404 handler
app.notFound((c) => c.json({ error: 'Not Found' }, 404));

// Error handler
app.onError((err, c) => {
  console.error(err);
  return c.json({ error: 'Internal Server Error' }, 500);
});

export default app;

import { Hono } from 'hono';

// Type bindings
type Bindings = {
  DB: D1Database;
};

const app = new Hono<{ Bindings: Bindings }>();

app.get('/users', async (c) => {
  const { results } = await c.env.DB.prepare(
    'SELECT * FROM users LIMIT 100'
  ).all();
  return c.json(results);
});

app.get('/users/:id', async (c) => {
  const id = c.req.param('id');
  const user = await c.env.DB.prepare(
    'SELECT * FROM users WHERE id = ?'
  ).bind(id).first();

  if (!user) {
    return c.json({ error: 'User not found' }, 404);
  }
  return c.json(user);
});

export default app;

# Deploy to production
npx wrangler deploy

# Deploy to a preview environment
npx wrangler deploy --env preview

# Stream live logs
npx wrangler tail

# Add a secret
npx wrangler secret put API_KEY
# Enter the value when prompted

# Access it in code
const apiKey = env.API_KEY;

# Stream logs in real time
npx wrangler tail

# Filter by error status
npx wrangler tail --format pretty --status error

name: Deploy to Cloudflare Workers

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Deploy
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CF_API_TOKEN }}