Document how to run User Worker on only specific paths

[nicolaic]

Summary

Adds a new section to Worker script routing documentation about how to configure routing such that a User Worker is only invoked on specific paths.

Documentation checklist

• The documentation style guide has been adhered to.

[hyperlint-ai]

Howdy and thanks for contributing to our repo. The Cloudflare team reviews new, external PRs within two (2) weeks. If it's been two weeks or longer without any movement, please tag the PR Assignees in a comment.

We review internal PRs within 1 week. If it's something urgent or has been sitting without a comment, start a thread in the Developer Docs space internally.

---

PR Change Summary

Added documentation on configuring User Workers to run on specific paths, enhancing the routing section for better clarity.

• Introduced a new section on selective path invocation for User Workers.
• Provided examples of configuration for routing in Worker scripts.
• Included a reference to the routing diagram for further guidance.

Modified Files

• src/content/docs/workers/static-assets/routing/worker-script.mdx

---

How can I customize these reviews?

Check out the Hyperlint AI Reviewer docs for more information on how to customize the review.

If you just want to ignore it on this PR, you can add the hyperlint-ignore label to the PR. Future changes won't trigger a Hyperlint review.

Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add hyperlint-ignore to the PR to ignore the link check for this PR.

[GregBrimble]

I'll need to double-check, but I had thought that:

(a) rules need to start with either / or !/,
(b) exclude rules were evaluated first (so this exclude would mean no path ever matches run_worker_first), and
(c) splats are greedy (so a double-splat in the exclude like this is meaningless)

@matthewdavidrodgers , can you confirm?

[matthewdavidrodgers]

yes to all three points; this is more effectively written as
"run_worker_first": ["/api/*"],

[matthewdavidrodgers]

to illustrate a situation where a negative path is necessary, it must also match a broader positive rule to exempt those paths from being directed to the worker.
e.g. "run_worker_first": ["/api/*", "!/api/docs/*"]

[matthewdavidrodgers]

yes to all three points; this is more effectively written as
"run_worker_first": ["/api/*"],

[matthewdavidrodgers]

Suggested change

	You can configure a User Worker to only be invoked on specific paths, by using an array of positive route patterns, followed by a negative wildcard pattern. This configuration can be very helpful when hosting a static website with a Worker as a simple backend service:
	You can configure a User Worker to only be invoked on specific paths by using an array of route patterns. This configuration can be very helpful when hosting a static website with a Worker as a simple backend service:

[matthewdavidrodgers]

to illustrate a situation where a negative path is necessary, it must also match a broader positive rule to exempt those paths from being directed to the worker.
e.g. "run_worker_first": ["/api/*", "!/api/docs/*"]

[nicolaic]

@matthewdavidrodgers As far as I can tell, that unfortunately does not achieve the desired behaviour of routing to the User Worker only on specific routes and no other routes, that was originally described in the documentation. Looking at the routing reference diagram indicates to me, the original configuration should, in theory, achieve this behaviour.

I haven't used Cloudflare Pages before, but I now see that I was mistaken, in thinking that you cloud achieve this with excludes field in _routes.json, which I assume in the intention that this routing behaviour is attempting to mimic?

I'm not doubtful that it is possible to achieve the configuration described, and perhaps my time could be spent better, either try update existing documentation to make this more clear, or maybe find an existing issue or create a new one regarding the desire for this behaviour.

I've tried to figure this out previously, and now again with the update run_worker_first config options, but in the end had to settle for having two separate Workers for both frontend and backend.

[GregBrimble]

If you want to just have single positive matches, that should just be run_worker_first = ["/foo", "/bar"]!