Routes
Background
Routes allow users to map a URL pattern to a Worker script to enable Workers to run on custom domains.
Custom zones
For zones proxied on Cloudflare*, route patterns decide what (if any) script is matched based on the URL of that request. Requests are routed through a Workers script when the URL matches a route pattern assigned to that script.
Route patterns can be added with the Cloudflare API or on the Workers tab in the Cloudflare dashboard (after selecting a zone).
Cloudflare Site routes are comprised of:
- Route URL (see Matching Behavior)
- Worker script to execute on matching requests
- Failure mode for rate-limited accounts on the free plan (see daily request limits)
The Routes REST API documentation can be found in the Workers API docs.
* A zone that you have registered with some registrar (not workers.dev) and setup Cloudflare to serve as a reverse proxy.
Matching Behavior
Route patterns look like this:
https://*.example.com/images/*
This pattern would match all HTTPS requests destined for a subhost of
example.com and whose paths are prefixed by /images/
.
A pattern to match all requests looks like this:
*example.com/*
While they look similar to a regex pattern, route patterns follow specific rules:
The only supported operator is wildcard
*
which matches zero or more of any character.Route patterns may not contain infix wildcards or query parameters, e.g. neither
example.com/*.jpg
norexample.com/?foo=*
are valid route patterns.When more than one route pattern could match a request URL, the most specific route pattern wins. For example, the pattern
www.example.com/*
would take precedence over*.example.com/*
when matching a request forhttps://www.example.com/
.Route pattern matching considers the entire request URL, including the query parameter string. Since route patterns may not contain query parameters, the only way to have a route pattern match URLs with query parameters is to terminate it with a wildcard,
*
.Route patterns are case sensitive, e.g.
example.com/Images/*
andexample.com/images/*
are two distinct routes.
A route can be specified without being associated with a worker; this will act to negate any less specific patterns. For example, consider this pair of route patterns, one with a Workers script and one without:
*example.com/images/cat.png -> <no script>*example.com/images/* -> worker-script
In this example, all requests destined for example.com and whose paths are prefixed by /images/
would be routed to worker-script
, except for /images/cat.png
, which would bypass Workers completely. Requests with a path of /images/cat.png?foo=bar
would be routed to worker-script
, due to the presence of the query string.
Validity
Here is the full set of rules governing route pattern validity:
Route patterns must include your zone
If your zone is example.com
, then the simplest possible route pattern you can have is example.com
, which would match http://example.com/
and https://example.com/
, and nothing else. As with a URL, there is an implied path of /
if you do not specify one.
Route patterns may not contain any query parameters
For example, https://example.com/?anything
is not a valid route pattern.
Route patterns may optionally begin with http:// or https://
If you omit a scheme in your route pattern, it will match both http:// and https:// URLs. If you include http:// or https://, it will only match HTTP or HTTPS requests, respectively.
https://*.example.com/
matcheshttps://www.example.com/
but nothttp://www.example.com/
*.example.com/
matches bothhttps://www.example.com/
andhttp://www.example.com/
.
Hostnames may optionally begin with *
If a route pattern hostname begins with *
, then it matches the host and all subhosts. If a route pattern hostname begins with *.
, then it matches only all subhosts.
*example.com/
matcheshttps://example.com/
andhttps://www.example.com/
*.example.com/
matcheshttps://www.example.com/
but nothttps://example.com/
Paths may optionally end with *
If a route pattern path ends with *
, then it matches all suffixes of that path.
https://example.com/path*
matcheshttps://example.com/path
andhttps://example.com/path2
andhttps://example.com/path/readme.txt
https://example.com/path/*
matcheshttps://example.com/path/readme.txt
but nothttps://example.com/path2
.
Subdomains must have a DNS Record
All subdomains must have a DNS record to be proxied on Cloudflare and used to invoke a Worker. For example, if you want to put a worker on myname.example.com
, and you've added example.com
to Cloudflare but have not added any DNS records for example.com
, any request to myname.example.com
will result in the error ERR_NAME_NOT_RESOLVED
.
To support this, you should use the Cloudflare dashboard to add an AAAA
record for myname
to example.com
, pointing to 100::
(the reserved IPv6 discard prefix).