A Simple Guide to Configuring Per-Branch Preview URLs for Cloudflare Workers with Wrangler

Must

1. Domain with Cloudflare

2. Empty GitHub repository

3. Node.js

The Essence

Step 1: DNS record

Create an A, AAAA, or CNAME record with a placeholder value. The value here doesn’t really matter, as Cloudflare will internally determine which Worker will process these requests using the Worker Routes configuration.

However, what is important is making sure the record is “Proxied”; otherwise, the Worker Routes configuration won’t work.

Note: To know more about the Cloudflare DNS Proxy.

Step 2: Wrangler

“Wrangler, the Cloudflare Developer Platform command-line interface (CLI), allows you to manage Worker projects.” — this page

If you don’t have wrangler globally installed, try this and then perform the following commands:

pnpm create cloudflare@latest wrangler-works --type hello-world --git --lang ts --deploy
cd wrangler-works
git remote add origin <empty-github-repo-url>
git push

Note: I’m using pnpm because I own the t-shirt. You can, of course, use whichever package manager’s merch you’re wearing, npm, yarn, or otherwise.

You should be able to access the worker through the free subdomain provided by Cloudflare, which might look like https://<worker-name>-<your-account-subdomain>.workers.dev. Be careful with the worker naming!

Step 3: Association

Even though we can access the worker through worker.dev It is not advised to use this domain in production.

Find the file named wrangler.jsonc or wrangler.toml and add the following:

/**
 * For more details on how to configure Wrangler, refer to:
 * https://developers.cloudflare.com/workers/wrangler/configuration/
 */
{
    ...
    "workers_dev": true,
    "preview_urls": true,
    "routes": [
        {
            "pattern": "journeyly.co/*",
            "zone_name": "journeyly.co"
        }
    ]
}

Follow that change up with deploying the worker with the new configuration:

pnpm run deploy

Step 4: DevOps

Go to the Worker settings and connect the GitHub Repository. Just make sure Builds for non-production branches is turned on.

Step 5: Assessment

Follow these steps to test your setup:

1. Make some changes to the src/index.ts

2. Create a new branch

3. Commit the changes

4. Push to remote

You should be able to see the following result on GitHub Actions when you click on the ✅ symbol on the latest commit of the new branch:

If we go one step further and open a pull request to merge into main, Cloudflare will automatically run deployment checks and display a message showing the status of your preview deployment.

Bonus

Now, what you do with this is up to you! Here’s what I am using it for:

export default {
    async fetch(request, _env, _ctx): Promise<Response> {
        const country = request.headers.get('CF-IPCountry') || 'XX';

        switch (country) {
            case 'IN':
                return Response.redirect('<redacted>', 302);
            default:
                return Response.redirect('<redacted>', 302);
        }
    },
} satisfies ExportedHandler<Env>;

Feeling generous with your good vibes today? Awesome! I’d be thrilled if you could take a minute to fill out this quick form for a project I’m working on. It would help me out so much! 🙌

Salutations!