Alright, let’s talk about running your TypeScript where there is no DOM. No window, no document, not even a setTimeout you can trust. We’re off to the races in the land of Cloudflare Workers, a globally distributed serverless platform that’s less “deploy a container” and more “shoot your code out of a cannon onto a CDN.”

Now, you might be thinking, “It’s V8, it’s JavaScript, how different could it be?” Oh, you sweet summer child. It’s a different planet. The first thing you’ll notice is that your code doesn’t run in response to a user clicking a button in a browser. It runs in response to an HTTP request. Your entire universe is a single fetch event.

The Event-Driven Life of a Worker

Your Worker’s existence is a cycle of waiting for and responding to events. You don’t start a server that listens on a port. Instead, you register an event listener for the fetch event. This is your main(), your init(), your whole world.

// This is your standard, no-frills Worker entry point.
export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    return new Response("Hello from the edge!", {
      headers: { 'content-type': 'text/plain' },
    });
  },
} satisfies ExportedHandler<Env>;

See that ExecutionContext? That’s your golden ticket. It gives you ctx.waitUntil() which is arguably the most important API for doing anything useful. Why? Because the moment you return that Response, the request is considered finished and the CPU could be yanked out from under your code. If you have any async tasks—logging, sending an email, updating a cache—you must pass their promise to ctx.waitUntil(promise). This tells the runtime, “Hey, I’m done with the request, but don’t kill this instance until this background task finishes.” Forget this, and your tasks will die silent, mysterious deaths. I’ve seen it happen. It’s not pretty.

The WinterCG: Your New Best Friend

You know how every Node.js alternative loves to be a “Node.js replacement”? It gets messy. To prevent the web from fracturing into a million incompatible server-side JS runtimes, the Web-interoperable Runtimes Community Group (WinterCG) was formed. Their goal: standardize a common set of APIs that work across all these environments (Workers, Deno, Bun, etc.).

Cloudflare Workers lean heavily on these standards. This is fantastic news for you. It means the Request, Response, URL, and fetch APIs you use are the exact same standard ones you know from the browser. This massively reduces the cognitive load. You’re not learning a whole new HTTP client library; you’re using fetch. You’re not parsing URLs with some niche url package; you’re using the URL class.

// Standard WinterCG/Web API usage. This will work in Deno, Bun, and Workers.
export default {
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    const name = url.searchParams.get('name') || 'Anonymous';

    // Need to fetch something from another API? Just use fetch.
    const someData = await fetch('https://api.example.com/data');
    
    return Response.json({ message: `Hello, ${name}!` });
  },
};

This is the biggest “why” it works this way: interoperability. Cloudflare has a vested interest in making it easy for you to bring code in and hard for you to leave. Adopting web standards is a brilliant way to do both.

Taming the TypeScript: @cloudflare/workers-types

Here’s where the designers made a choice you’ll either love or tolerate: there is no Node.js. No require, no __dirname. Your process.env is a different, much cooler beast. To keep TypeScript from screaming bloody murder about all these missing globals, you need to install and use @cloudflare/workers-types.

npm install -D @cloudflare/workers-types

Then, in your tsconfig.json, you point it at the Cloudflare environment. This is non-negotiable. If you skip this step, you’ll be in a world of red squiggles.

{
  "compilerOptions": {
    "target": "es2021",
    "lib": ["es2021"],
    "types": ["@cloudflare/workers-types"]
  }
}

This types package defines the Request, Env, and ExecutionContext parameters for you. It’s what makes your development experience actually pleasant. Which brings me to…

The Env Binding: This is the Way

In the old days, you’d use process.env.SECRET_KEY. In Workers, the environment is explicitly passed into your handler. This is a genuinely good idea. It makes dependencies explicit, easy to test, and typesafe.

You define your bindings—for KV namespaces, D1 databases, R2 buckets, secrets, etc.—in your wrangler.toml configuration file. Then, you create a type interface for them.

// In your TypeScript file
export interface Env {
  // A secret, like an API key
  MY_SECRET: string;
  // A KV namespace
  MY_KV: KVNamespace;
  // A custom binding you might have
  MY_CUSTOM_BINDING: Fetcher;
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    // Now you can access them in a fully typed way!
    const secret = env.MY_SECRET; // TypeScript knows this is a string
    const value = await env.MY_KV.get('some-key'); // TypeScript knows this method exists

    // ... do work ...

    return new Response('Done!');
  },
};

This design is airtight. It prevents you from accidentally deploying code that tries to access an environment variable that doesn’t exist in your production environment. The compiler will catch it. Thank the engineers for this one.

Common Pitfalls: It’s the Little Things

  1. The Global Scope Gotcha: You can’t use the global scope for storing state between requests. Each request might hit a completely different isolate in a different part of the world. If you try to set a global variable, the next request won’t see it. Use KV, Durable Objects, or a real database for state.
  2. The Date Object is a Liar: The Date.now() inside a Worker reflects the time at the data center where your code is running, which is probably not your local timezone. Always use UTC and be explicit about time zones if you’re doing anything time-sensitive.
  3. Mind the CPU Time: Workers are meant to be short-lived. There’s a strict CPU time limit. Don’t try to do complex image processing or train a machine learning model in there. It’s for quickly handling requests and responding, not for long-running computations.

So, there you have it. Writing for Cloudflare Workers is less about learning a new framework and more about internalizing a new, event-driven, globally-distributed mindset. Use the WinterCG APIs, lean on the TypeScript definitions, and for the love of all that is holy, remember your ctx.waitUntil(). Now go build something fast.