Pages Functions compiles 224 route files into one 1.35 MB Worker

Evidence status

Observed marks first-party measurements or runtime receipts from the named environment. Derived marks arithmetic calculated from cited inputs. Specified marks vendor or standards documentation. Implemented and deployed name code and live-state evidence, respectively. Reproduced means the stated procedure was rerun. Externally attested marks operator reports; those reports show that an experience occurred, not that it is universal.

The file tree is the router, and there is no other route table

Cloudflare's routing document states it in one line: your /functions directory structure determines the routes. Real paths from this repository:

Three bracket forms, and they behave differently:

functions/a/[slug].js answers /a/thing and not /a/thing/extra. The catch-all answers /api/articles/x/y/z and receives context.params.path as ["x","y","z"]. If no Function matches, Pages falls through to a static file with that name. Trailing slashes are ignored.

A handler file exports up to eight functions, one per HTTP method

The API reference is explicit about the interaction between them: onRequest is called unless a more specific onRequestVerb is exported. Export both onRequest and onRequestGet and a GET only ever reaches onRequestGet. The eight names are onRequest, onRequestGet, onRequestPost, onRequestPut, onRequestPatch, onRequestDelete, onRequestHead, onRequestOptions. Counted across this repository today:

grep -rhoE '^export (async )?(function|const) onRequest[A-Za-z]*' functions --include='*.js' \
  | grep -oE 'onRequest[A-Za-z]*' | sort | uniq -c | sort -rn

Every handler receives one argument, the EventContext. Its useful members: request, env (your bindings), params (the bracket captures), next() (pass through to the next Function or to the static asset server), waitUntil() (finish work after the response is sent) and passThroughOnException().

One middleware file sits in front of 100 percent of traffic

_middleware.js is the only filename Pages treats as middleware. At functions/_middleware.js it runs in front of the entire application, static files included. At functions/users/_middleware.js it runs only for requests under /users. It calls context.next() to hand the request onward and can rewrite what comes back. This application has exactly one, 946 lines, exporting a single onRequest. Its order is a property of that file, not of Pages:

1. Edge cache lookup for public, cacheable reads.
2. Lean-body branch: a crawler or model fetcher gets the same content from a KV snapshot with the stylesheet stripped, marked private so no shared cache can hand it to a person.
3. adminGate(context), before any handler sees the request.
4. machineDataGuard: a browser navigating to a raw /api/ URL gets a readable page, a machine gets JSON.
5. ?bundle=1 redirects to the object-folder endpoint.
6. context.next() into the matched handler.
7. Category header on every response, injections, cache write.

Two things to know before putting this much into middleware. You may export an array instead of a function — export const onRequest = [errorHandling, authentication] — and entries run in order, so the first can catch throws from the rest. And CPU spent in middleware is charged against the same per-request budget as the handler, because they are the same Worker invocation.

An optional catch-all can beat a static file with the same name

Cloudflare's routing document says: "More specific routes (routes with fewer wildcards) take precedence over less specific routes." Read plainly, a real filename beats [[path]].js. This repository does not trust it. At functions/api/articles/[[path]].js line 788:

// Canonical Knowledge-Action subresources share the existing article router.
// Keep this dispatch explicit because the optional catch-all route can outrank a
// same-name static function for `/skill` on Pages.

The layout that produces the ambiguity:

functions/api/articles/
├── [[path]].js                  ← matches /api/articles/**
└── design-law/
    ├── index.js
    └── skill.js                 ← matches /api/articles/design-law/skill exactly

Both can serve GET /api/articles/design-law/skill. The static skill.js exports onRequestGet and returns markdown; the catch-all carries a branch at the top of its handle() returning byte-identical markdown for the same path. The response proves nothing about which one ran:

$ curl -sI https://miscsubjects.com/api/articles/design-law/skill
HTTP/2 200
content-type: text/markdown; charset=utf-8
content-disposition: inline; filename="SKILL.md"

That symmetry is the defence: because both return the same bytes, either can win the route and the site behaves. Delete the branch in the catch-all and you are betting the endpoint on precedence resolving your way.

The rule: specificity is scored, not guaranteed by having a real filename. When a catch-all and a static file overlap, either make the catch-all handle the path too, or move the static file out of its subtree.

_routes.json decides whether a request costs anything

Once a functions/ directory exists, every request invokes the Worker by default, including requests for fonts and images a Function was never going to touch. _routes.json takes routes back. It lives in the build output directory — public/ here, not the repository root — and has three keys: version, include, exclude. Exclude always wins over include. This project's file, complete:

{
  "version": 1,
  "description": "Tell Cloudflare Pages NOT to handle these paths — they belong to the miscsubjects-admin Worker via its route bindings.",
  "include": ["/*"],
  "exclude": [
    "/site.html", "/site", "/showcase", "/showcase.html",
    "/widgets", "/widgets.html", "/font/*", "/control", "/spec",
    "/edit/*", "/article/*", "/condition/*",
    "/import-export", "/import", "/export"
  ]
}

One include rule and fifteen exclude rules: sixteen of the hundred allowed. The file's own limits are a trap — at least one include rule is required, no more than 100 rules combined, none longer than 100 characters. A wildcard matches any number of segments, so /font/* covers everything below /font/.

Two reasons the exclude list matters, and only one is money. Excluding /font/* means a font request never enters this Worker's CPU budget and never counts as an invocation; static requests on Pages are free and unlimited, Function invocations bill at the Workers rate. The second is correctness: those paths are claimed by a separate Worker bound to those routes, and leaving them included would mean this Worker answered first.

HANDOFF_CLAUDE_CODE.md says 387 handlers; 213 files actually handle a request

Re-counted today the total is still 387 — but "handlers" flatters it. That figure counts every JavaScript module under functions/, and 164 are shared library code that never answers a URL.

find functions -name '*.js' -not -name '*.test.*' | wc -l                                  # 387
find functions -name '*.js' -not -path 'functions/_lib/*' -not -name '*.test.*' | wc -l    # 223
find functions/_lib -name '*.js' -not -name '*.test.*' | wc -l                             # 164
grep -rlE '^export (async )?(function|const) onRequest' functions --include='*.js' | wc -l # 213

Ten route files export no handler — functions/a/writing-law.js, functions/api/design-law.js and eight others export helpers that neighbouring route files import. They still compile into the bundle. Where the routes live: functions/api/ 124, functions/admin/ 42, functions/ root 26, functions/a/ 7, functions/oip/ 3, functions/content/ and functions/.well-known/ 2 each, 17 further single-file directories.

find functions -name '*.js' -not -path 'functions/_lib/*' -not -name '*.test.*' \
  | awk -F/ '{ if (NF==2) print "functions/ (root)"; else print "functions/"$2"/" }' \
  | sort | uniq -c | sort -rn

The limits, with the numbers the documentation carries today

Fetched 25 July 2026 from Cloudflare's Pages limits page (last updated 16 July 2026) and Workers limits page. Pages Functions are Workers, so compute and size come from the Workers page, asset limits from the Pages page.

Four of these bite differently than the table suggests.

Only the gzipped number counts. OpenNext's Cloudflare troubleshooting page is blunt: "When deploying your Worker, wrangler will show both the original and compressed sizes. Only the latter (gzipped size) matters for these limits." A 5 MB index.js is not automatically a problem.

CPU time is not wall time. Waiting on a fetch(), a KV read or a D1 query does not count. Cloudflare's own figure: the average Worker uses about 2.2 ms per request. 10 ms free is tight for server-side rendering, generous for a handler that mostly awaits I/O.

Subrequests count binding calls. A KV read, an R2 get and a D1 query are each one. A handler looping one D1 query per item hits the free ceiling at 50 items.

The 500-per-month cap is on Git-integration builds, not deploys. A Direct Upload — wrangler pages deploy from a machine, how this project ships — is not a Pages build, and preview deployments are explicitly unlimited. The current limits page carries no deployments-per-month cap at all.

workers.api.error.script_too_large: three walls, three different exits

That string is the API error returned when the compiled bundle exceeds the plan's size limit. It is the most common way a growing Pages project stops deploying, and it never appears locally, because local development uploads nothing. Three real reports, failing for three different reasons.

Too many pages compiled into the script. Jeffh30 on Stack Overflow, 25 September 2023, deploying a SvelteKit blog: "I now have more than 200 posts with multiple components each. Everything was working well, but recently started getting the following error when deploying to Cloudflare pages". No individual post was wrong; the framework compiled every one into _worker.js, and around 200 the total crossed the ceiling.

One binary larger than the whole allowance. matthewjewell on nuxt-modules/og-image issue 193, 13 April 2024: "Tried deploying a branch with a simple template, it works well locally, but with the 1mb worker limit on Pages (free) I get the workers.api.error.script_too_large error as the compiled-wasm file is 2.4mb." A single 2.4 MB WebAssembly file against a then-1 MB free ceiling. No code-splitting saves that; the asset has to leave the bundle.

Neither — the upload itself dies. revmischa on cloudflare/workers-sdk issue 1194, 6 June 2022: "When I upload to pages with wrangler 2 it goes reaaallly slow and then crashes" — a roughly 300 MB site that uploaded fine under wrangler 1, crawling then failing at 809 of 8009 files. That is the asset pipeline, not the script limit, and it earns a mention because from the terminal it looks identical: a deploy that does not finish.

One correction before copying a fix from any of those threads: the free ceiling those two hit was 1 MiB, and it is 3 MB today. Cloudflare raised the Workers Free script limit from 1 MiB to 3 MiB in late November 2024. A project blocked in 2023 may deploy unchanged now.

Measured: 5.07 MiB of compiled source, 1.29 MiB gzipped

wrangler pages functions build runs the same compilation the deploy runs and writes the Worker to a directory instead of uploading it. Take this measurement before believing anything about your headroom.

cd /path/to/your/pages/project
npx wrangler pages functions build --outdir /tmp/pf-build
#  ✨ Compiled Worker successfully
find /tmp/pf-build -type f
#  /tmp/pf-build/index.js
stat -f "%z" /tmp/pf-build/index.js          # macOS; stat -c %s on Linux
#  5316456
gzip -c /tmp/pf-build/index.js | wc -c
#  1349068

Run against this repository on 25 July 2026 with wrangler 4.103.0, all 387 modules compile to one file:

Two conclusions. This application sits at 45% of the free ceiling and 13.5% of the paid one — nowhere near the wall. And it would have failed the old 1 MiB free limit by 29%: the same 387 modules could not have been deployed to a free account before November 2024. The 3.94× ratio is why judging by uncompressed size is useless: 5.07 MiB looks alarming against "3 MB" and is under half of it.

Cold and warm, measured over eighteen requests from one client

Cold-start figures for Workers are usually vendor-quoted. These were taken on 25 July 2026 against a live Pages Function on this site, published with the command so the spread is visible instead of one flattering figure.

cat > /tmp/fmt.txt <<'EOF'
dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} ttfb=%{time_starttransfer} total=%{time_total} code=%{http_code}\n
EOF

# New TLS connection each time, cache-busted so the edge cache cannot answer
for i in 1 2 3 4 5; do
  curl -s -o /dev/null -w "@/tmp/fmt.txt" \
    "https://miscsubjects.com/api/articles/cloudflare-os-functions?cb=$RANDOM$i"
done

# Eight requests on one reused connection
curl -s -w "@/tmp/fmt.txt" \
  $(for i in $(seq 8); do echo -n "-o /dev/null https://miscsubjects.com/api/articles/cloudflare-os-functions "; done)

Median time to first byte: 145 ms for the Function route on a warm connection, 68 ms for the excluded static route. The Function route ran a D1 query and assembled a JSON document; the font returned cf-cache-status: HIT. Not like-for-like, and the gap is not a measurement of routing overhead — but it is the honest size of the difference between a path that enters the Worker and a path _routes.json keeps out.

The spread is the finding. The slowest new-connection run took 5.1× the fastest. Any single-number latency claim about Pages Functions from one client is noise.

A 500 with an empty body, and nothing to look at

Uninen on Hacker News, 24 February 2025: "a CloudFlare pages function would return 500 + nonsensical error and an empty response in prod. Tried to figure this out all Friday. It was super annoying to fix as there's no way to add more logging".

Partly still true.

Live tailing works. wrangler pages deployment tail, run in the project directory, streams every invocation of the current production deployment as structured JSON — outcome, exceptions with stack and message, logs from your own console.log, and the request and response objects. The dashboard shows the same stream. It is live, so it shows a failure only while you are watching and reproducing it.

Persistent, queryable logs do not. Cloudflare's own Pages-to-Workers compatibility matrix marks Workers Logs, Logpush, Tail Workers and Source Maps unsupported on Pages and supported on Workers. Real-time logs is the only row supported on both. On Pages you cannot look at what happened an hour ago, and a minified stack trace stays minified because source maps do not upload.

What to do instead, in order:

1. Reproduce with wrangler pages deployment tail running. The exceptions array carries the message and stack the empty 500 withheld.
2. Wrap middleware in try/catch and return the error. Cloudflare's own middleware example does exactly this — return new Response(err.message + "\n" + err.stack, { status: 500 }) — turning an empty 500 into a readable one. Gate it behind a header so it is not public.
3. If the Worker throws at module scope, no handler runs and no console.log inside one will ever fire. A module-scope throw takes the whole deployment down, which is exactly the "empty response" shape. Check top-level code and imports first.
4. If you need logs you can query after the fact, that is Workers, not Pages.

Pages or Workers: a verdict for each row

Cloudflare's position, from its own migration guide: "Unlike Pages, Workers has a distinctly broader set of features available to it, (including Durable Objects, Cron Triggers, and more comprehensive Observability)." Static asset requests are free on both and Function invocations bill at the same rate, so cost is not the deciding variable. Two blockers stop people who want to follow that advice.

merek on Hacker News, 10 August 2025: "I had to use Pages since Workers don't support \"Custom domains outside Cloudflare zones\" [1]. There's no way I can transfer the domain since I have subdomains tightly integrated with AWS services." The compatibility matrix confirms it — custom domains outside Cloudflare zones is the one row marked supported on Pages and unsupported on Workers.

scottydelta, same thread, same day: "I recently ported an entire TS project from cloudflare workers to a django python app since cloudflare workers don't support choice of region/country when deploying workers." Placement Hints now bias a Worker toward a named cloud region — placement.region set to something like aws:us-east-1 — but Cloudflare is explicit that Workers run on its network rather than inside cloud regions, so a hint is a latency optimisation. Guaranteed geographic confinement is Regional Services, and the documentation states it is an Enterprise add-on.

What this application would have to change to move: file-based routing across 223 route files becomes an explicit router — the 32 catch-alls map to prefix routes, the 19 single-segment files to path patterns. _routes.json has no Workers equivalent and becomes route configuration plus the static-asset binding. public/ becomes an assets binding. In exchange: Workers Logs, source maps, cron triggers, and the ability to split when the bundle grows. Nothing in that list is hard. Nothing in it is urgent at 45% of the free ceiling.

✨ Uploading Functions bundle is the line that proves the deploy shipped code

cd /path/to/your/pages/project     # NOT optional — see below
npx wrangler pages deploy public --project-name <your-project> --branch main

public is the build output directory. Wrangler uploads the files in it, compiles functions/ from the current working directory into one Worker, and uploads _routes.json from the output directory. A real successful deploy of this project printed:

✨ Compiled Worker successfully
Uploading... (4/4)
✨ Success! Uploaded 0 files (4 already uploaded) (0.61 sec)
✨ Uploading Functions bundle
✨ Uploading _routes.json
🌎 Deploying...
✨ Deployment complete!

The absence of the Functions-bundle line is the failure mode. Wrangler resolves functions/ relative to the shell's working directory, not relative to the output-directory argument. Run the same command from one directory up and it uploads the static files perfectly, finds no functions/, ships a Functions-less deployment, and every dynamic route starts returning 404 or 405 — a full production outage from a command that printed no error. Redeploy from the project directory. Nothing else fixes it, because the deployment that shipped genuinely contains no Worker.

What the ship script refuses to do

scripts/ship.mjs wraps that same command in gates. Each gate corresponds to a way a deploy has already gone wrong.

The preview-first step carries a subtlety that generalises to any Pages project with a database. Preview deployments bind to a separate, empty preview database, so any page whose first act is a populated query returns 500 on preview while being perfectly healthy in production. The script splits the smoke sets accordingly: the preview set holds only pages that render from code, the production set holds the data pages. A module-scope error takes the entire Worker down, so it still surfaces on preview even though the data pages cannot be checked there.

Symptom, cause, fix

Related

• One Cloudflare account, one build — the map of every component and which binding reaches it.
• Workers and Durable Objects — the six things that are separate Workers, and the three tests for when a job stops belonging in this deployment.

The fresh compiler receipt moved the file count, not the architecture

Wrangler 4.103.0 compiled the current working tree at 2026-07-26T05:55:10.960Z. The measurement wrote its output only to a temporary directory.

The three extra modules since the 25 July inventory produced one extra route file, two extra shared modules, one extra handler-bearing file and one extra GET export. The deployment shape did not change: every route and shared module still landed in one Worker bundle.

Reproduce the bundle measurement:

OUTDIR="$(mktemp -d)"
npx wrangler pages functions build --outdir "$OUTDIR"
stat -f "%z" "$OUTDIR/index.js"          # macOS
gzip -c "$OUTDIR/index.js" | wc -c

Expected proof line: ✨ Compiled Worker successfully. Judge the plan limit against the gzip result, not the first number.