Cloudflare Docs
Visit Workers on GitHub
Set theme to dark (⇧+D)

Custom Domains

​​ About Custom Domains

Custom Domains allow you to connect your Worker to a hostname, without having to make changes to your DNS settings or do extra certificate management. Cloudflare will create DNS records and issue necessary certificates on your behalf. The created DNS records will point directly to your Worker.

​​ Build a Custom Domain

To create a Custom Domain, you must have:

  1. An active Cloudflare zone on your target domain.
  2. A Worker to invoke.

The interface provides active feedback on valid and invalid entries. Valid entries are hostnames on an active Cloudflare zone. If you attempt to create a Custom Domain on a hostname with an existing DNS record, Cloudflare will confirm that you would like to replace the existing record. Custom Domains can be attached to your Worker via API or within the Cloudflare dashboard under Account Home > Workers > your Worker > Triggers > Add Custom Domain.

​​ Configure your wrangler.toml

To configure a subdomain in your wrangler.toml, add the following to your environment:

routes = [
{ pattern = "", custom_domain = true }

​​ Fetch

Custom Domains are considered the origin for your request. This means calling fetch() on the initial request is, in most cases, an anti-pattern. Instead, create new Request objects to reference any external dependencies, or use Cloudflare’s built in primitives via bindings.

Workers can use the fetch API to request external dependencies

Another benefit of integration with Cloudflare DNS is that you can use your Custom Domains like you would any external dependency. Your Workers can fetch() Custom Domains and invoke their associated Worker, even if the Worker is on the same Cloudflare zone. The newly invoked Worker is treated like a new top-level request and will execute in a separate thread.

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

​​ Ordering

Custom Domains follow standard DNS ordering and matching logic. Custom Domains do not support wildcard records; as such, an incoming request must match the hostname your Custom Domain is registered to. Other parts of the URI are not considered when executing this matching logic. For example, if you create a Custom Domain on attached to your api-gateway Worker, a request to either or would invoke the same api-gateway Worker.

Custom Domains follow standard DNS ordering and matching logic

​​ Interaction with Routes

Custom Domains are evaluated before Route rules, but take lower precedence. Routes defined on your Custom Domain will run first, but can optionally call the Worker registered on your Custom Domain. In the example above, a Custom Domain for can point to your Worker api. A Route added to can point to your Worker auth. Using fetch(request) within the Worker auth will invoke the Worker api, as if it was a normal application server. This means you can run your Workers in series, creating layers of proxy Workers and application Workers.

Routes can be run in front of Custom Domains

​​ Migrate from Routes

If you are currently invoking a Worker using a Route with /*, and your DNS points to 100:: or similar, a Custom Domain is a recommended replacement.

To migrate the Route*, create a Custom Domain on, replacing the existing record. You can then delete the route* in your Account Home > Workers > your Worker > Triggers > Routes table.

Unless that Worker acts exclusively as a proxy – meaning it will need to call fetch(request) on the incoming connection’s HTTP request to connect to an application server defined in DNS – the Custom Domain is the recommended solution.