Custom Domains

Background

Custom Domains allow you to connect your Worker to a domain or subdomain, without having to make changes to your DNS settings or perform any certificate management. After you set up a Custom Domain for your Worker, Cloudflare will create DNS records and issue necessary certificates on your behalf. The created DNS records will point directly to your Worker. Unlike Routes, Custom Domains point all paths of a domain or subdomain to your Worker.

Custom Domains are routes to a domain or subdomain (such as example.com or shop.example.com) within a Cloudflare zone where the Worker is the origin.

Custom Domains are recommended if you want to connect your Worker to the Internet and do not have an application server that you want to always communicate with. If you do have external dependencies, you can create a Request object with the target URI, and use fetch() to reach out.

Custom Domains can stack on top of each other. For example, if you have Worker A attached to app.example.com and Worker B attached to api.example.com, Worker A can call fetch() on api.example.com and invoke Worker B.

Custom Domains can stack on top of each other, like any external dependencies

Custom Domains can also be invoked within the same zone via fetch(), unlike Routes.

Add a Custom Domain

To add a Custom Domain, you must have:

An active Cloudflare zone.
A Worker to invoke.

Custom Domains can be attached to your Worker via the Cloudflare dashboard, Wrangler or the API.

Set up a Custom Domain in the dashboard

To set up a Custom Domain in the dashboard:

In the Cloudflare dashboard, go to the Workers & Pages page.
Go to Workers & Pages
In Overview, select your Worker.
Go to Settings > Domains & Routes > Add > Custom Domain.
Enter the domain you want to configure for your Worker.
Select Add Custom Domain.

After you have added the domain or subdomain, Cloudflare will create a new DNS record for you. You can add multiple Custom Domains.

Set up a Custom Domain in your Wrangler configuration file

To configure a Custom Domain in your Wrangler configuration file, add the custom_domain=true option on each pattern under routes. For example, to configure a Custom Domain:

{
  "routes": [
    {
      "pattern": "shop.example.com",
      "custom_domain": true
    }
  ]
}

[[routes]]
pattern = "shop.example.com"
custom_domain = true

To configure multiple Custom Domains:

{
  "routes": [
    {
      "pattern": "shop.example.com",
      "custom_domain": true
    },
    {
      "pattern": "shop-two.example.com",
      "custom_domain": true
    }
  ]
}

[[routes]]