Writing Your First Worker: A Practical Guide to Cloudflare Deployment

Previously in this course, we covered the Introduction to Wrangler CLI, where we installed the necessary tools and initialized our project directory. Now that your environment is ready, it is time to write your first Worker.

At its core, a Cloudflare Worker is a function that sits between a user's browser and your origin server. Instead of just passing a request through, the Worker intercepts it, allowing you to manipulate the request, generate a response entirely at the edge, or even fetch data from other services.

Understanding the Request-Response Pattern

Workers follow a simple, event-driven model. When a request hits the Cloudflare network, your script receives a Request object and must return a Response object. If you don't return a response, the request will fail.

Here is how the interaction looks in code:

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

This is the most basic "Hello World" script. The fetch method is the entry point. It receives the incoming request, an env object (used for bindings like D1 or R2, which we will cover later in the course), and a ctx (context) for background tasks.

Running Your Script Locally

Before deploying to the global network, we always verify code locally. Wrangler provides a built-in development server that simulates the Cloudflare environment.

1. Navigate to your project directory.
2. Run the following command: npx wrangler dev

Wrangler will start a local server, usually at http://localhost:8787. Open this URL in your browser, and you will see your "Hello World" message. Because this runs locally, you can modify the string in your index.js file, save it, and refresh the page to see your changes instantly—no deployment required.

Deploying to the Cloudflare Edge

Once you are satisfied with your local testing, moving to production is a single command. Deployment pushes your code to Cloudflare's global network, where it will be executed at an edge location closest to your users.

Run the following in your terminal: npx wrangler deploy

Wrangler will bundle your code, upload it to Cloudflare's platform, and provide you with a URL (e.g., my-worker.your-subdomain.workers.dev). Visit that link, and you are officially running serverless code on the edge.

Hands-on Exercise: Customizing the Response

Let's move beyond "Hello World." Modify your index.js file to return a JSON object instead of plain text.

1. Update your code:

   JAVASCRIPT
   export default {
     async fetch(request, env, ctx) {
       const data = {
         message: "Hello from the Edge",
         timestamp: new Date().toISOString()
       };
       return new Response(JSON.stringify(data), {
         headers: { "Content-Type": "application/json" }
       });
     },
   };
   

2. Test it locally with npx wrangler dev.
3. Deploy your changes with npx wrangler deploy.

Common Pitfalls

• Forgetting the Response: Every fetch handler must return a Response object. If you perform logic but don't return anything, the browser will hang or return a 500 error.
• Blocking the Event Loop: Avoid long-running synchronous loops. Workers are designed for fast, asynchronous operations. If you have background cleanup tasks, use ctx.waitUntil() to ensure they finish without delaying the response to the user.
• Environment Mismatch: Ensure you are authenticated with the correct account if you have multiple Cloudflare organizations. Use wrangler whoami to verify your current identity before deploying.

Frequently Asked Questions

Q: Does every Worker need a route? A: Not necessarily. When you deploy a Worker, it is assigned a .workers.dev URL. You can later map it to a custom domain using Routes or Custom Domains, which we will explore in later lessons.

Q: Is there a limit to how much code I can write? A: Yes, there are limits on script size and execution time, but they are very generous for most use cases. For beginners, the primary constraint is keeping your logic efficient to minimize latency.

Q: How do I handle different HTTP methods (GET, POST)? A: You can inspect request.method inside your fetch function to route traffic differently based on whether the user is fetching data or submitting it.

Recap

In this lesson, we created a functional Worker, tested it in a local environment using the Wrangler CLI, and deployed it to the global edge. You’ve now mastered the request-response cycle that is the foundation for all Cloudflare Workers applications.

Up next: We will dive into Handling HTTP Requests, where you will learn to inspect headers and customize responses based on client data.