Workers Routes and Custom Domains: A Developer’s Guide

Previously in this course, we covered managing secrets securely and environment configuration. Now that your application is secure and configurable, it’s time to move it from the generic workers.dev environment to your own production domain.

Mapping a Worker to a custom domain is the final step in transitioning from a prototype to a professional-grade web service.

Understanding Routing from First Principles

By default, every Cloudflare Worker is accessible via a *.workers.dev subdomain. While perfect for testing, it isn't suitable for a public-facing application. When you use Routing, you tell Cloudflare’s edge network to intercept specific HTTP requests incoming to your domain and pass them to your Worker logic instead of your origin server.

Routing works by matching an incoming request URL against a pattern. If a match is found, the Worker executes. If not, the request proceeds through the standard Cloudflare proxy flow (e.g., reaching your origin server or cache).

Configuring Routes in wrangler.toml

To map your Worker, you define routes within your wrangler.toml configuration file. A route is essentially a string pattern that acts as a filter for traffic.

Open your project’s wrangler.toml file and add the following configuration:

TOML
# wrangler.toml
name = "my-worker-app"
main = "src/index.js"

# Define your production domain route
routes = [
  { pattern = "api.yourdomain.com/*", zone_name = "yourdomain.com" }
]

The Routing Pattern Anatomy

• pattern: This is the URL structure you want the Worker to handle. The * is a wildcard that matches any path segment following the prefix.
• zone_name: The root domain where this route applies.

Once this is configured, any request hitting api.yourdomain.com/users or api.yourdomain.com/v1/data will trigger your Worker.

Mapping to a Custom Domain

To make this work, you must ensure your domain is active on Cloudflare and that the DNS record for the subdomain exists.

1. DNS Check: In your Cloudflare Dashboard, go to DNS. Ensure a CNAME record exists for api.yourdomain.com pointing to a dummy IP (like 192.0.2.1) if you aren't using an origin server, or your actual server IP if you are.
2. Proxy Status: The DNS record must be proxied (the orange cloud icon must be enabled). Routing only works when traffic flows through the Cloudflare edge network.

Hands-on Exercise

Let’s apply this to our ongoing project. We want our API to live at api.example.com instead of the default worker URL.

1. Update your wrangler.toml to include the routes block shown above, replacing yourdomain.com with your actual domain.
2. Run npx wrangler deploy.
3. Observe the CLI output. Wrangler will confirm the routes have been registered to your zone.
4. Test the integration by hitting your new URL:

   Bash
   curl -I https://api.yourdomain.com/
   

5. If configured correctly, you should see your Worker's response headers.

Common Pitfalls

• Missing Proxy: If your DNS record is set to "DNS Only" (grey cloud), the request never touches the Cloudflare edge, and your Worker will never trigger.
• Route Overlap: If you define a catch-all route (e.g., example.com/*), it might accidentally intercept traffic intended for your static assets. Be as specific as possible with your patterns.
• Deployment Delays: DNS propagation is usually fast, but sometimes it takes a minute or two for the new route to propagate across the global edge network after deployment.

Frequently Asked Questions

Q: Can I map multiple routes to one Worker? A: Yes. You can add multiple entries to the routes array in wrangler.toml to handle different paths or subdomains with the same code.

Q: What happens if I don't set a route? A: Your worker remains reachable at the default *.workers.dev URL, but it will not intercept any traffic on your custom domain.

Q: Is there a limit to how many routes I can have? A: The number of routes is limited by your Cloudflare plan, but for most projects, the default limits are more than sufficient.

Recap

Routing is the mechanism that bridges your edge code with your public-facing domain. By using wrangler.toml to define patterns, you gain fine-grained control over which traffic hits your application logic. This setup is essential for integrating routing logic or implementing versioned routes within your infrastructure.

Up next: We will explore Advanced Routing Patterns, including how to split traffic between different Workers and manage route priority.