How to Build and Deploy a Global Edge API with Cloudflare Workers in 15 Minutes

How to Build and Deploy a Global Edge API with Cloudflare Workers in 15 Minutes

As a backend developer with 8 years of Java experience, I am frequently asked by junior team members and friends: "Is there a way to deploy lightweight endpoints onto low-latency global nodes without buying cloud servers, configuring Nginx, or managing Docker containers?" Previously, this often meant struggling with Kubernetes or multi-cloud disaster recovery setups, which are costly and maintenance-heavy.

In this tutorial, I will walk you through a complete edge application development lifecycle using the Cloudflare Workers SDK (specifically the core CLI tool, Wrangler). By the end of this guide, you will be able to write a dozen lines of TypeScript code locally and deploy it to 300+ edge nodes worldwide with a single command, establishing a highly available RESTful API.

I. Prerequisites

Before we begin, please ensure your development machine meets the following requirements:

• Node.js ≥ 18 (recommended v20 LTS) with npm or pnpm ready.
• A free Cloudflare account registered (no credit card required).
• Basic Knowledge: Familiarity with TypeScript syntax and the HTTP Request/Response model. No Linux server or Ops experience is required.

II. Quick Start: Scaffolding and Environment Simulation

The official team has provided a blazing-fast scaffold. Open your terminal and execute:

npm create cloudflare@latest my-edge-api

Follow the prompts to select the Hello World TypeScript template and enable Git initialization. Once the project is generated, don't rush to write code yet. First, open the wrangler.toml file in the root directory. This is the "ID card" for your Worker:

name = "my-edge-api"
main = "src/index.ts"
compatibility_date = "2024-10-01"

• name: Defines the unique identifier for your application, which serves as the context for subsequent CLI operations.
• main: Points to the entry file. Unlike traditional HTTP servers, the entry point for Workers is a Fetch Handler function exported via default export.
• compatibility_date: Crucial! This locks the underlying V8 engine version and available API sets, directly determining whether your code runs on new or old nodes. It is recommended to keep the default or update it monthly; the official team uses this date to distinguish feature stability.

Why not use node src/index.ts?
Workers run in a highly isolated V8 Sandbox environment. They disable Node core modules like fs, net, and only expose standard Web APIs (e.g., Fetch, URL, Crypto).

The correct approach is to run the Wrangler development server:

npx wrangler dev

This starts a proxy server at localhost:8787 that fully simulates the edge runtime, supporting HMR (Hot Module Replacement). When you save code in your editor, the local environment reloads instantly. Wrangler manages the network layer in the background, simulating Cloudflare's edge routing logic, allowing you to test most request linkages offline.

III. Practical: Building a Global Node Probe & Latency API

Many developers are used to express, but for edge environments, I highly recommend Hono. It is lightweight (16kb), zero-dependency, and built entirely on web standards. We will write an endpoint that returns the "request hit node city, client IP, and processing latency."

1. Install dependency: npm install hono
2. Replace the content of src/index.ts:

import { Hono } from 'hono';
const app = new Hono();

app.get('/api/edge-info', async (c) => {
  const start = performance.now();
  
  // Workers unique metadata, containing the edge node the request passed through,
  // TLS version, etc.
  const cfMetadata = c.req.raw.cf || {};
  
  const end = performance.now();
  
  return c.json({
    status: "success",
    latency_ms: parseFloat((end - start).toFixed(2)),
    edge_colo: (cfMetadata as any).colo || "unknown",
    tls_ver: c.req.raw.headers.get("cf-tls-version") || "unknown",
    tip: "Deployed via workers-sdk (wrangler)"
  }, 200);
});

export default app;

The core of this code lies in c.req.raw.cf. When a request hits the Cloudflare edge, the network layer automatically injects a wealth of metadata (such as colo airport codes, city, continent). We read this directly, eliminating the need for third-party geoip libraries or database queries, completely saving network round-trips and memory overhead. The code exports a standard fetch event handler, complying with modern web norms.

To verify and deploy, run: npx wrangler deploy.
The CLI will automatically bundle, compress, and upload your code to Cloudflare's V8 isolate cluster, assigning a *.workers.dev subdomain. Usually within 10 seconds, your API is live globally.

IV. Wrangler CLI & Configuration Summary

Here are the core commands and configuration you need:

#[wrangler.toml]
name = "my-edge-api"
main = "src/index.ts"
compatibility_date = "2024-10-01"

## Launch local simulation (simulates edge runtime)
npx wrangler dev

## One-click deployment to production
npx wrangler deploy

V. Common Issues & Pitfalls

• CPU Time Budget Limits: The free tier strictly limits a single request to approximately 10ms CPU time (with a total wall-clock time of 50s). Edge instances are designed for "fast in, fast out". Do not run synchronous crypto or heavy image compression here. Leave that for ECS or Serverless containers (like AWS Fargate).
• KV Read Eventual Consistency: If you use Cloudflare KV for caching or configuration, note that it is an eventual consistency architecture. Global synchronization after a write can take up to 60 seconds. For scenarios requiring strong consistency, please switch to D1 or R2 combined with a caching strategy, or accept the brief delay.
• Secure Environment Variable Injection: You must use npx wrangler secret put DB_KEY to inject production secrets. Never hardcode them in source code or .env files pushed to GitHub. During local debugging, Wrangler automatically reads the .dev.vars file in the root directory, allowing you to manage dev-state configurations securely and conveniently.
• Debugging Remote State: By default, wrangler dev uses local simulation. If you want to connect directly to online KV/D1 for debugging, add the --remote parameter, but proceed with caution to avoid polluting production data.

VI. Conclusion

From npm create initialization to wrangler dev local debugging, and finally wrangler deploy global distribution, we have effectively completed a modern Serverless delivery pipeline.

Edge computing is not here to replace core services like Java/SpringBoot; its position is to help you intercept high-frequency, low-latency requests like "static resource rendering, lightweight authentication, and API gateway aggregation" at the periphery, letting your main cluster focus on complex transaction processing.

Next Steps: Try mounting D1 (Edge SQLite Relational Database) in wrangler.toml or integrate @ai-sdk/openai to upgrade this basic scaffold into a true AI Agent Gateway or global cache layer. Run it once, and you'll find that development in the cloud-native era can truly be light as a feather.