A Worker route runs edge code for matching requests on a Cloudflare-managed hostname. Attach new code to a narrow path first so it cannot unintentionally intercept every page or integration.
IN THIS ARTICLE
What you need before you begin
Deploy and test the Worker in an appropriate development environment. Confirm the zone, proxied DNS record, required bindings and expected behaviour for requests the code does not handle itself.
01 Attach a Cloudflare Worker to a narrowly scoped route
- Open Workers & Pages and select the intended Worker.
- Go to Settings > Domains & Routes > Add > Route.
- Select the zone and enter a deliberately narrow route pattern, such as one hostname and application path. Review existing overlapping routes.
- Add the route and test matching requests with the actual hostname, path and method. Verify the Worker’s handling or origin fetch behaves as intended.
- Test nonmatching paths, observe logs and metrics, and expand the scope only after the limited deployment is stable. Keep the route-removal and code-rollback steps available.
02 Example: attach a Worker to one HTTPS test path
In an existing, reviewed Wrangler project, the following routes fragment targets only the HTTPS test area on one proxied hostname. Merge it with the project configuration rather than replacing unrelated settings or routes. Replace the example zone and hostname with the intended test deployment.
{
"routes": [
{
"pattern": "https://www.example.com/edge-preview/*",
"zone_name": "example.com"
}
]
}After the reviewed deployment, test /edge-preview/check and a request with a query string. Also check /contact/, /edge-preview-extra/ and another hostname. The path is case sensitive, and /edge-preview without the trailing slash is outside this pattern.
Expected result: only the intended test path invokes this route, subject to any more-specific overlapping route. Verify Worker logs and the real response. A route pattern is not a regular expression, and its configuration is separate from publishing the Worker code.
Confirm the expected result
The Worker should affect only the intended traffic and preserve required origin behaviour. Check authentication, caching and response headers as well as the visible page.
Troubleshoot unexpected results
A Worker route and a Worker Custom Domain serve different routing designs. Use a route when code should run in front of an existing proxied origin; review Custom Domains for a Worker acting as the origin itself. Route patterns are not arbitrary regular expressions.
Does saving code automatically attach it to my hosting domain?
Not necessarily. Deployment and routing are separate configuration elements. Check the Worker’s active version and its Domains & Routes settings together.