When a Cloudflare Pages project's build output contains a _worker.js file, what happens to its functions/ directory, and what must that Worker do?
answer
- one file takes over
- file routing and middleware ignored
- module syntax only
- assets only through env.ASSETS
basics
~20 sA _worker.js in the build output switches the Pages project to advanced mode: the functions/ directory, its routing and its middleware are ignored. The file is a module Worker that receives every request and must call env.ASSETS.fetch() to serve static files.
solid answer
~40 sAdvanced mode starts when the build output directory contains `_worker.js`. Pages then ignores the `functions/` directory completely, with its file routing and `_middleware.js` files, and deploys `_worker.js` as the project's Worker. It must use ES module syntax, `export default { async fetch(request, env, ctx) { ... } }`, and it receives every request that `_routes.json` lets through, by default all of them. Pages no longer serves static files on its own for those requests: the Worker routes them itself and hands the rest to `env.ASSETS.fetch(request)`, or the site's pages stop loading. `context.passThroughOnException()` is not available in this mode, and bindings arrive on `env`. Teams usually reach advanced mode through a framework adapter that emits `_worker.js`, or when moving an existing Worker onto Pages.
code
javascript · 10 lines// <build output>/_worker.js
export default {
async fetch(request, env, ctx) {
const url = new URL(request.url);
if (url.pathname.startsWith("/api/")) {
return Response.json({ mode: "advanced", path: url.pathname });
}
return env.ASSETS.fetch(request);
},
};go deeper
Recall that a _worker.js file in the build output replaces the functions/ directory and must call env.ASSETS.fetch() for static files.
Explain what stops running (file routing, middleware, passThroughOnException), why module syntax is required, and that _routes.json still narrows which requests reach the Worker.
Spot the migration hazards: a framework adapter silently disabling functions/, a missing ASSETS fallback breaking pages, and every static request billed when no custom _routes.json exists.
Weigh staying on Pages advanced mode against moving to a Worker with static assets, given that Cloudflare now points new projects at Workers.
## Two ways to write server code on Pages A Cloudflare Pages project can run server-side code in one of two forms: | | Pages Functions (`functions/`) | Advanced mode (`_worker.js`) | |---|---|---| | Where the code lives | `functions/` at the project root | `_worker.js` in the build output directory | | Routing | from the file tree | written in the Worker | | Middleware | `_middleware.js` files | written in the Worker | | Handler shape | `onRequest(context)` exports | `export default { fetch(request, env, ctx) }` | | Static files | served automatically when no route matches | only through `env.ASSETS.fetch()` | | Generated `_routes.json` | yes, from the tree | no; all requests by default | Advanced mode exists for applications that do not fit file-based routing: an existing Worker with its own router, or a framework whose build emits a single Worker. Some full-stack framework adapters for Pages produce `_worker.js` for exactly this reason. ## What changes when `_worker.js` appears 1. **`functions/` is ignored.** The routes, the `_middleware.js` files and any helpers imported only from there stop running. Wrangler builds `_worker.js` and skips the directory, without failing the build. 2. **The Worker gets every request** that `_routes.json` lets through. Without a custom `_routes.json`, that is every request, static files included. 3. **Module syntax is required.** The file must `export default` an object with a `fetch` handler; the documentation does not support the Service Worker form with `addEventListener` for `_worker.js`. 4. **`passThroughOnException()` is unavailable.** In file-based Functions it falls back to the asset server on an uncaught error; in advanced mode the Worker handles its own errors. 5. **The file is not served as an asset.** `_worker.js` is deployed as code, so its source is not downloadable from the site. ## Serving the static site Because the Worker owns the request, Pages does not fall back to static assets for it. The Worker must forward non-API requests to the **`ASSETS` binding**, which every Pages project gets automatically: - `env.ASSETS.fetch(request)` returns what the asset server would have returned, with the project's `_headers` and `_redirects` rules applied. - Pass the "pretty" path: `/users/` rather than `/users/index.html`. - Forgetting this call breaks every page the Worker does not answer itself. ## Bindings, routes and limits stay the same - **Bindings** configured for the project (KV, D1, R2, secrets, vars) arrive on `env`, the same values file-based Functions read from `context.env`. - **`_routes.json` still applies.** A custom file in the build output can exclude static trees so they skip the Worker and stay free; without one, every request is a billed Workers request. - **Billing and limits** are those of Workers requests, as for file-based Functions. - **Compatibility date and flags** come from the project's settings or its Wrangler file, exactly as they do for a `functions/` directory. ## Moving an existing Worker in The documented migration path for a standalone Worker is short: 1. Copy the Worker's module code into `_worker.js` in the project's build output directory. 2. Add `return env.ASSETS.fetch(request);` as the fallback for every path the Worker does not answer. 3. Recreate the Worker's bindings, vars and secrets on the Pages project, in the dashboard or in a Wrangler file with `pages_build_output_dir`. 4. Deploy through the Git integration or `wrangler pages deploy`, then confirm both an API path and a static page. Locally, `wrangler pages dev ./public` detects `_worker.js` in the directory and runs it in place of `functions/`. ## Typical mistakes - Keeping a `functions/` folder after a framework starts emitting `_worker.js`, and wondering why the contact route stopped answering. - Writing `_worker.ts` and expecting Pages to compile it; Pages reads `_worker.js`, so compile TypeScript to that file. - Returning `404` for unknown paths instead of calling `env.ASSETS.fetch()`, which breaks the site's own pages. - Shipping a `_routes.json` that includes only `/api/*` and then adding page-level logic to the Worker, which never runs because page requests no longer reach it. ## Where advanced mode sits today As of October 2026, Cloudflare's documentation tells teams to start new projects on Workers, and a Worker with static assets offers the same "one Worker in front of a static site" shape that advanced mode gives a Pages project. Advanced mode remains supported for existing Pages projects and for adapters that target Pages.
- A Pages project has both functions/api/contact.js and a framework-emitted _worker.js. Which one answers /api/contact?The `_worker.js` file. When it is present, Pages ignores the whole `functions/` directory, so `contact.js` and every `_middleware.js` stop running. Port the contact route into the framework's own routing, or into the Worker's `fetch` handler.
- How do you keep image requests from invoking an advanced-mode Worker on Pages?Ship a custom `_routes.json` in the build output with an `exclude` rule such as `/images/*`. Advanced mode generates no routes file, so without one every request invokes the Worker; excluded requests go straight to the asset server and are not billed as Workers requests.
- In advanced mode, Pages still runs the _middleware.js files before _worker.js.
- Pages serves static files automatically when _worker.js returns nothing for a path.
- A _worker.js file may use the addEventListener Service Worker syntax.
- Pages compiles a _worker.ts file in the build output.
- Advanced mode ignores the project's _routes.json.
As of 2026-10-10, Cloudflare's Pages documentation tells teams to start new projects on Workers; advanced mode remains supported for existing Pages projects.