About Custom Domains
Custom Domains allow your 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:
- An active Cloudflare zone on your target domain.
- 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 > > your Worker > Triggers > Add Custom Domain.
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.
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 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
api.example.com attached to your
api-gateway Worker, a request to either
api.example.com/user would invoke the same
Interaction with Routes
Custom Domains are evaluated before Route rules, but take lower precedence. 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
api.example.com can point to your Worker
api. A Route added to
api.example.com/auth can point to your Worker
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.
Migrate from Routes
To migrate the Route
app.example.com/*, create a Custom Domain on
app.example.com, replacing the existing record. You can then delete the route
app.example.com/* in your Account Home > > 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.