Cloudflare Pages and Workers

Cloudflare Pages hosts static sites (with optional Functions) from a Git repo or a direct upload, and Workers runs JavaScript at the edge. Both use the wrangler CLI. Account setup, tokens, Tunnel and R2 are in Cloudflare.

Documentation: Pages · Workers · Wrangler commands · Workers limits

Verification: commands and config were read on developers.cloudflare.com (one page each) and not run here. Marked (unverified) where a page did not confirm it.

Pages or Workers #

Cloudflare’s docs do not call Pages deprecated, but they steer new projects towards Workers, which has a broader feature set, and publish a migration guide. Workers static assets supports _headers and _redirects natively. A “Workers is recommended for all new projects” statement was only seen in secondary sources (unverified).

Pages: Wrangler #

Pages: Git Builds #

• Root directory defaults to the repo root. Set it for a monorepo.
• Set NODE_VERSION as an environment variable, or use .nvmrc or .node-version.
• System variables available in builds: CF_PAGES, CF_PAGES_BRANCH, CF_PAGES_COMMIT_SHA, CF_PAGES_URL.
• The production branch defaults to the first branch you push. Other branches build as previews, and include and exclude rules accept * (excludes are evaluated first).
• Older build images are being retired: v1 projects move to v3 on 2026-09-15 and v2 on 2027-02-23.
• Preview URL format: (unverified).

Pages: Custom Domains #

• Add the domain in the dashboard first, or you get a 522.
• Apex domain: the zone must be on Cloudflare with its nameservers.
• Subdomain: CNAME to <SITE>.pages.dev.

Pages: wrangler.jsonc #

{
  "name": "my-site",
  "pages_build_output_dir": "./dist",
  "compatibility_date": "2026-01-01"
}

main does not apply. Only env.production and env.preview exist. Once the file is used, the dashboard settings become read-only.

Pages: _redirects and _headers #

Put both files in the build output directory.

# _redirects: SOURCE DESTINATION [CODE]
/old-page  /new-page  301
/blog/*    /news/:splat  302

# _headers: URL line, then indented headers
/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff

Pages: Functions #

Files under functions/ become routes.

Export onRequest, or a method form: onRequestGet, onRequestPost, onRequestPut, onRequestPatch, onRequestDelete, onRequestHead, onRequestOptions.

_routes.json limits which paths invoke Functions:

{
  "version": 1,
  "include": ["/api/*"],
  "exclude": ["/api/static/*"]
}

exclude wins. Limits: 100 rules combined, 100 characters per rule.

Workers: Wrangler #

Workers: wrangler.jsonc #

{
  "name": "my-worker",
  "main": "src/index.js",
  "compatibility_date": "2026-01-01",
  "assets": { "directory": "./public", "not_found_handling": "single-page-application" },
  "routes": [{ "pattern": "app.example.com", "custom_domain": true }],
  "vars": { "ENVIRONMENT": "production" },
  "kv_namespaces": [{ "binding": "CACHE", "id": "<KV_ID>" }],
  "r2_buckets": [{ "binding": "FILES", "bucket_name": "my-bucket" }],
  "d1_databases": [{ "binding": "DB", "database_name": "my-db", "database_id": "<D1_ID>" }],
  "triggers": { "crons": ["*/3 * * * *"] }
}

• name cannot contain underscores.
• not_found_handling takes single-page-application, 404-page or none. run_worker_first sends requests to the Worker before assets.
• Routes can also be { "pattern": "...", "zone_name": "example.com" }.

Workers: Handlers #

export default {
  async fetch(request, env, ctx) {
    return new Response("ok");
  },
  async scheduled(controller, env, ctx) {
    // runs on each cron trigger
  },
};

The fetch form is the standard shape but its docs page was not fetched (unverified). Test a cron locally with wrangler dev --test-scheduled, then:

curl "http://localhost:8787/cdn-cgi/local/scheduled?cron=*+*+*+*+*"

Free Plan Limits #

The paid plan allows 30 s CPU by default, up to 5 minutes. Check Workers limits before relying on these numbers.

See Also #

• Cloudflare
• Cloudflare Speed Test
• Cloudflare Tunnel Recipe