Skip to content

Document how to run User Worker on only specific paths #23218

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Document how to run User Worker on only specific paths #23218

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions src/content/docs/workers/static-assets/routing/worker-script.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,3 +127,44 @@ export default class extends WorkerEntrypoint<Env> {
}
```
</TypeScriptExample>

### Run Worker only on selective paths

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:
Copy link
Contributor

@matthewdavidrodgers matthewdavidrodgers Jun 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:


For more information you can take a look at the [routing reference diagram](/workers/static-assets/routing/static-site-generation/#reference).

<WranglerConfig>

```json
{
"name": "my-worker",
"compatibility_date": "$today",
"main": "./worker/index.ts",
"assets": {
"directory": "./dist/",
"not_found_handling": "single-page-application",
"binding": "ASSETS",
"run_worker_first": ["/api/*", "!**"]
Copy link
Contributor

@GregBrimble GregBrimble Jun 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

@matthewdavidrodgers matthewdavidrodgers Jun 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

@matthewdavidrodgers matthewdavidrodgers Jun 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/*"]

}
}
```

</WranglerConfig>

<TypeScriptExample filename="./worker/index.ts">

```ts
import { WorkerEntrypoint } from "cloudflare:workers";

export default class extends WorkerEntrypoint<Env> {
async fetch(request: Request) {
// This Worker script is only called for requests on paths starting with `/api/`
return Response.json({
success: true,
message: 'Hello from API endpoint',
});
}
}
```
</TypeScriptExample>