Cloudflare Pages File Limit for Astro: Pages vs Workers

Count the build output before choosing a platform#

Run the same build that your deployment uses, then inspect the generated directory:

1
pnpm build
2
find dist -type f | wc -l
3
du -sh dist
4
find dist -type f -size +25M -print

The file count is the first limit to compare. The individual Cloudflare Pages asset limit is currently 25 MiB, so a site can fail even when its file count is small if one generated asset is too large. Treat the output from find as a deployment input; do not count only Markdown or source files.

Choose Pages, paid Pages, or Workers#

For large content sites, also ask why every page is being pre-rendered. A lower file count can come from changing the rendering strategy, but that may introduce runtime CPU, caching, and routing requirements. Do not trade a file-count error for an untested SSR deployment.

Keep a static Astro build simple#

Cloudflare’s Astro guide notes that a purely static Astro site does not need the Cloudflare adapter. Astro can generate dist/ and the host can serve those files as static assets. A minimal Workers Static Assets configuration is conceptually:

1
{
2
  "$schema": "./node_modules/wrangler/config-schema.json",
3
  "name": "my-astro-site",
4
  "compatibility_date": "2026-08-17",
5
  "assets": {
6
    "directory": "./dist",
7
    "not_found_handling": "404-page"
8
  }
9
}

The assets.directory value must match the directory produced by your Astro build. The not_found_handling choice should match the routes you actually generate; a static content site should not use an SPA fallback merely to hide missing files.

If you keep using Pages on a paid plan, set PAGES_WRANGLER_MAJOR_VERSION=4 in the Pages project environment as Cloudflare documents. Merely installing a newer local CLI does not prove that the Pages build environment uses the setting required for the higher limit.

Migrate from Pages without mixing output models#

Cloudflare’s Pages-to-Workers migration guide maps a Pages build output setting to an assets.directory entry and uses wrangler deploy for the Worker deployment. The migration checklist is:

1. Record the current build command and the exact directory Pages uploads.
2. Run pnpm build locally and compare the resulting dist/ tree.
3. Replace pages_build_output_dir with assets.directory only when the project is using Workers Static Assets.
4. Keep a deliberate compatibility_date and review preview URL behavior.
5. Deploy a non-production version and request representative HTML, CSS, image, and 404 paths.
6. Switch the custom domain only after the generated URLs and redirects match the Pages deployment.

The migration guide was updated on August 14, 2026, but the values above are still deployment inputs that should be checked against the current Cloudflare documentation before a production change.

Do not use static assets for an SSR requirement#

The Cloudflare adapter changes Astro’s output toward on-demand rendering. Use it when the site needs request-time logic, sessions, or bindings. The existing Astro Cloudflare session binding guide covers the separate case where a deploy creates an unexpected SESSION KV binding.

If the project is a content-heavy static site, inspect the generated data and chunking before selecting SSR. Astro content collection storage can reduce the risk of one oversized generated data file, but it does not change Cloudflare’s total static-file limit.

Takeaway#

Count the deployed dist/ files first. Choose paid Pages or paid Workers Static Assets when the build fits below 100,000 files, and choose an Astro Worker only when request-time behavior is part of the requirement. Neither product removes the need to control generated output.

FAQ#