Routes

Background

Routes allow users to map a URL pattern to a Worker. When a request comes in to the Cloudflare network that matches the specified URL pattern, your Worker will execute on that route.

Routes are a set of rules that evaluate against a request’s URL. Routes are recommended for you if you have a designated application server you always need to communicate with. Calling fetch() on the incoming Request object will trigger a subrequest to your application server, as defined in the DNS settings of your Cloudflare zone.

Routes add Workers functionality to your existing proxied hostnames, in front of your application server. These allow your Workers to act as a proxy and perform any necessary work before reaching out to an application server behind Cloudflare.

Routes can fetch() Custom Domains and take precedence if configured on the same hostname. If you would like to run a logging Worker in front of your application, for example, you can create a Custom Domain on your application Worker for app.example.com, and create a Route for your logging Worker at app.example.com/*. Calling fetch() will invoke the application Worker on your Custom Domain. Note that Routes cannot be the target of a same-zone fetch() call.

Set up a route

To add a route, you must have:

1. An active Cloudflare zone.
2. A Worker to invoke.
3. A DNS record set up for the domain or subdomain proxied by Cloudflare (also known as orange-clouded) you would like to route to.

Warning

Route setup will differ depending on if your application’s origin is a Worker or not. If your Worker is your application’s origin, use Custom Domains.

If your Worker is not your application’s origin, follow the instructions below to set up a route.

Note

Routes can also be created via the API. Refer to the Workers Routes API documentation for more information.

Set up a route in the dashboard

Before you set up a route, make sure you have a DNS record set up for the domain or subdomain you would like to route to.

To set up a route in the dashboard:

1. Log in to the Cloudflare dashboard ↗ and select your account.
2. Go to Workers & Pages and in Overview, select your Worker.
3. Go to Settings > Triggers > Routes > Add route.
4. Enter the route and select the zone it applies to.
5. Select Add route.

Set up a route in wrangler.toml

Before you set up a route, make sure you have a DNS record set up for the domain or subdomain you would like to route to.

To configure a route using your wrangler.toml file, refer to the following example.

routes = [
  { pattern = "subdomain.example.com/*", zone_name = "example.com" }
  # or
  { pattern = "subdomain.example.com/*", zone_id = "<YOUR_ZONE_ID>" }
]

Add the zone_name or zone_id option after each route. The zone_name and zone_id options are interchangeable. If using zone_id, find your zone ID by logging in to the Cloudflare dashboard ↗ > select your account > select your website > find the Zone ID in the lefthand side of Overview.

To add multiple routes:

routes = [
  { pattern = "subdomain.example.com/*", zone_name = "example.com" },
  { pattern = "subdomain-two.example.com/example", zone_id = "<YOUR_ZONE_ID>" }
]

Note

The zone_id and zone_name options are interchangeable. However, if using Cloudflare for SaaS with a */* pattern, use the zone_name option to avoid errors. Currently, publishing */* routes with a zone_id option fails with an Invalid URL error ↗.

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 the wildcard (*), which matches zero or more of any character.

• Route patterns may not contain infix wildcards or query parameters. For example, neither example.com/*.jpg nor example.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 for https://www.example.com/. The pattern example.com/hello/* would take precedence over example.com/* when matching a request for example.com/hello/world.

• 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, *.

• The path component of route patterns is case sensitive, for example, example.com/Images/* and example.com/images/* are two distinct routes.

• For routes created before October 15th, 2023, the host component of route patterns is case sensitive, for example, example.com/* and Example.com/* are two distinct routes.

• For routes created on or after October 15th, 2023, the host component of route patterns is not case sensitive, for example, example.com/* and Example.com/* are equivalent 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

The following set of rules govern 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/ matches https://www.example.com/ but not http://www.example.com/.

• *.example.com/ matches both https://www.example.com/ and http://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 only matches all subhosts.

• *example.com/ matches https://example.com/ and https://www.example.com/.

• *.example.com/ matches https://www.example.com/ but not https://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* matches https://example.com/path and https://example.com/path2 and https://example.com/path/readme.txt

Warning

There is a well-known bug associated with path matching concerning wildcards (*) and forward slashes (/) that is documented in Known issues.

Domains and subdomains must have a DNS Record

All domains and 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 have added example.com to Cloudflare but have not added any DNS records for myname.example.com, any request to myname.example.com will result in the error ERR_NAME_NOT_RESOLVED.

Warning

If you have previously used the Cloudflare dashboard to add an AAAA record for myname to example.com, pointing to 100:: (the reserved IPv6 discard prefix ↗), Cloudflare recommends creating a Custom Domain pointing to your Worker instead.