Hosting static sites on Cloudflare Workers

Start here / The mental model

What are we hosting, and which Cloudflare service does what?

A static site sends files that already exist: HTML pages, CSS, browser JavaScript and images. It can still have interactive menus, search and calculators in the browser. A dynamic backend runs code when a request arrives, for example to validate a contact form or look up a customer's records. You can host the static part first and add a backend only where it is needed.

The upload and delivery model uses Workers static assets. Product descriptions below follow Cloudflare's documentation as of Sep 2026.

Workers vs R2 vs D1: code, files and records

These services do different jobs and can work together. A brochure site needs only static assets. A site with contact forms adds Worker code and perhaps D1. A site with large downloads or user uploads can add R2.

Start with the smallest setup: static assets for pages; a Worker script for request-time behavior; D1 for queryable records; R2 for separately managed files. Now the limits, configuration keys and migration steps below have a place to fit.

00 / Quick reference

Cloudflare Workers static assets: limits and decisions

01 / How a request flows

How does a request reach a Workers static asset?

Ten hops, in order. Most migration bugs are a rule sitting at the wrong hop: a Page Rule that is no longer consulted, a header rule that never sees a Worker-built response, a trailing-slash redirect answered by html_handling before your 301 line could run (because the line was never written).

1. Proxied DNS record.

   The existing orange-cloud A/CNAME stays exactly as it was. A route needs a proxied record on an active zone; the origin IP behind it stops mattering once the route exists.

2. Zone rules.

   Single Redirects run in the first request phase (http_request_dynamic_redirect), then URL rewrites, config and origin rules, WAF custom rules, rate limiting, managed rules, Super Bot Fight Mode, Bulk Redirects, header transforms, Cache Rules. A matching Single Redirect answers before any Worker runs.

   Bot Fight Mode can challenge your own CI runners and parity probes (403 with cf-mitigated).

3. Page Rules.

   For requests served by a Worker route, a Forwarding URL Page Rule is ignored (Cloudflare's "Workers with Page Rules" table). Always Use HTTPS is still respected; Browser Cache TTL and Rocket Loader are ignored. A forwarding Page Rule on a host silently stops firing at cutover.

4. Route match.

   Most specific pattern wins: walletrecovery.info/api/* beats walletrecovery.info/*. * is the only operator, paths are case-sensitive, and a route with no Worker punches a hole in a broader one.

5. Worker script, if the path is in run_worker_first.

   Matching globs invoke your script (billed); everything else goes straight to assets (free). Without run_worker_first, the script runs only when no asset matched.

   From compatibility date 2025-04-01, browser navigations (Sec-Fetch-Mode: navigate) that miss get not_found_handling instead of the script whenever it is set.

6. _redirects.

   Evaluated before asset matching, so a redirect fires even when a file exists at the source path. Static lines are checked, then dynamic (splats, placeholders). First match wins; 200 lines rewrite without chaining.

7. Asset lookup and html_handling.

   Finds the file, and normalizes non-canonical forms with 307. A path whose percent-encoding is non-canonical is also 307'd to the canonical encoding.

8. not_found_handling.

   404-page serves the nearest 404.html walking up the tree with status 404; single-page-application serves /index.html with 200; none (the default) hands off to the script if there is one, else a bare 404.

9. _headers.

   Attached to asset responses, including those fetched by your script through env.ASSETS.fetch(). Not applied to responses your script builds itself; set those headers in code.

10. Response, and what it can reach.

    A script can call other Workers through service bindings (no extra request charge, and the target needs no route at all), D1, KV and R2. Assets are cached at the edge with tiered cache and default to Cache-Control: public, max-age=0, must-revalidate plus an ETag.

02 / wrangler.jsonc, key by key

Which wrangler.jsonc keys does a static site need?

Values are what the fleet runs on 2026-09-28. The account id is pinned in each repo's wrangler.jsonc; ids never appear on this page.

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "coloradofirearmswatch-org",
  "compatibility_date": "2026-09-27",
  "account_id": "<ACCOUNT_ID>",   // pin it
  "assets": {
    "directory": "./dist",
    "html_handling": "auto-trailing-slash", // canonical /a/
    "not_found_handling": "404-page"    // ship dist/404.html
  },
  "workers_dev": false,   // no public *.workers.dev copy
  "preview_urls": true,   // parity target per upload
  // Uncomment on cutover day, commit, deploy --full-parity.
  "routes": [
    { "pattern": "coloradofirearmswatch.org/*",
      "zone_name": "coloradofirearmswatch.org" }
  ]
}

{
  "name": "cheatsheets-davidveksler-com",
  "main": "workers/site/index.js",
  "compatibility_date": "2026-09-28",
  "account_id": "<ACCOUNT_ID>",
  "assets": {
    "directory": "./dist",
    "binding": "ASSETS",
    "html_handling": "none",        // canonical URLs end .html
    "not_found_handling": "404-page",
    // generated by the build; 42 entries, cap is 100
    "run_worker_first": [
      "/", "/*.php", "/_x/*", "/404.html",
      "/popularity", "/sitemap.xml", "/subscribe",
      "/confirm", "/software-devops", "/software-devops/"
      // ...one pair per category hub
    ]
  },
  "services": [   // forms Worker has no route of its own
    { "binding": "FORMS",
      "service": "cheatsheets-davidveksler-com-forms" }
  ],
  "observability": { "enabled": true },
  "workers_dev": false,
  "preview_urls": true,
  "routes": [
    { "pattern": "cheatsheets.davidveksler.com/*",
      "zone_name": "davidveksler.com" }  // the zone
  ]
}

03 / Porting nginx

How do you migrate nginx rules to Cloudflare Workers?

Everything nginx did implicitly has to be written down. The most dangerous losses are the silent ones: server-wide headers, slashless variants a regex used to catch, and status codes an assets-only Worker cannot send.

Worked example: WalletRecovery's nginx map to _redirects

Six real lines from deploy/redirects.map (53 active rules), plus the one non-ASCII source in the map. The converter parses each source target; line, percent-encodes the source with Python's quote(source, safe="/-._~!$&'()*+,;=:@%"), writes 301, and exits 1 above 2,000 lines.

map $uri $redirect_uri {
    default "";
    /about-david/                          /about/;
    /blog/                                 /articles/;
    /connect/                              /contact/;
    /contact-us/                           /contact/;
    /data-recovery-shipment-instructions/  /shipping/;
    /frequently-asked-questions/           /faq/;
    /2022/11/18/how-i-recover-stolen-nfts-from-crypto-scammers-🥷🏼/  /articles/how-i-recover-stolen-nfts-from-crypto-scammers/;
}
# server block: if ($redirect_uri) { return 301 $redirect_uri; }

# hand-written rules first; first match wins
/tools/:tool/offline.html /tools/:tool/offline 200
# generated from deploy/redirects.map
/about-david/ /about/ 301
/blog/ /articles/ 301
/connect/ /contact/ 301
/contact-us/ /contact/ 301
/data-recovery-shipment-instructions/ /shipping/ 301
/frequently-asked-questions/ /faq/ 301
/2022/11/18/how-i-recover-stolen-nfts-from-crypto-scammers-%F0%9F%A5%B7%F0%9F%8F%BC/ /articles/how-i-recover-stolen-nfts-from-crypto-scammers/ 301

Result, curl on 2026-09-28: the encoded emoji URL answers 301 /articles/how-i-recover-stolen-nfts-from-crypto-scammers/. The hand-written first line exists because auto-trailing-slash would 307 the saved offline.html tool copies that nginx served with 200.

04 / The guarded deploy pipeline

How do you deploy with wrangler versions upload and a preview URL?

Upload a version without serving it, prove it matches production byte for byte, stop for a human, then promote. Every fleet repo runs a copy of one template, scripts/deploy-cloudflare.sh plus a PowerShell twin.

1. 01 preflightClean tree; Node ≥ 22; npm ci if wrangler missing; token from CLOUDFLARE_API_TOKEN (CI) or a local env file; parity script present; routed? parsed from wrangler.jsonc.
2. 02 build + gatesSite build and its lint/SEO gates. Fails if the build modified any tracked file.
3. 03 uploadwrangler versions upload --preview-alias c<sha> --tag <sha>. A brand-new Worker is bootstrapped with wrangler deploy first (unrouted only).
4. 04 paritycf_parity.py: preview vs production. Smoke by default; full when unrouted or --full-parity.
5. 05 stop?Unrouted or --preview-only: exit 0, "preview ready, production unchanged".
6. 06
   human
   confirm
   [y/N]
7. 07 promotewrangler versions deploy <id>@100% --yes, then wrangler triggers deploy (routes), then a host cache purge that only warns on failure.
8. 08 live verifyLoop until: distinctive string present (here-string grep), prod body of the verify path hashes equal to the preview's, and wrangler deployments status output contains the version id.

Step 08 checks that the version id appears in deployments status; it does not parse the percentage. The loop has a fixed ceiling, but a correct verifier passes on the first iteration: a slow pass means a broken check, not "propagation" (see incident 2026-09-28, SIGPIPE).

Parity: what "matches production" means

05 / Cutover, soak, rollback, decommission

How do you cut over from nginx to Workers with zero DNS change?

git commit -am "Cut over to Workers: enable route"
scripts/deploy-cloudflare.sh --full-parity

06 / Forms and beacons without a server

How do you replace a PHP contact form with a Worker, D1 and Turnstile?

A contact form is the last reason most static sites keep PHP. The kit's contact-Worker template handles one POST in this order; each step is cheap and the expensive calls come last.

1. Route and method.

   GET ?health=1 returns JSON booleans for D1, Turnstile secret and mail config: 200 when all present, 503 otherwise. Any other non-POST: 405.

2. Config check, fail closed.

   Missing DB, TURNSTILE_SECRET or mail config: 500 with the "not configured" message. A half-configured form never silently eats messages.

3. Honeypot.

   A hidden field with any value returns the normal success response. No send, no log, no signal to the bot.

4. Rate limit (D1, fixed window).

   Key: SHA-256 of salt|cf-connecting-ip, truncated to 12 bytes. One row per hit in hits; 2% of calls prune rows older than 24 h. Fails open on a D1 error: a database blip must not block real inquiries. WalletRecovery: 5 per 900 s. Exceeded: 429.

5. Field validation.

   Required fields enforced (422); each field trimmed, length-capped and pattern-checked per the site config.

6. Turnstile siteverify.

   POST https://challenges.cloudflare.com/turnstile/v0/siteverify with secret, response and remoteip = cf-connecting-ip. Tokens are single-use and expire after 300 s.

7. Mail send.

   Mailgun or Resend, chosen per site. A provider failure returns 502.

8. D1 log row, after the send.

   INSERT INTO inquiries (ts, data) with attribution fields only, so the count means "inquiries delivered". A logging failure is swallowed: the email already went out.

9. Response.

   fetch() callers (X-Requested-With: fetch or Accept: application/json) get JSON {ok, error}. Plain form posts get 303 to the success or failure page, so the form works with JavaScript off.

The template's test suite runs 13 assertions under wrangler dev: health, 405, unknown path 404, honeypot success, missing field 422, bad email 422, missing token 422, send reached (502 against a stub), no-JS 303, 429 after 5 posts, beacon 204, beacon health, event row stored. Beacons (handleEvent) always answer 204 whatever happens, with their own rate cap (default 120 per window).

CREATE TABLE IF NOT EXISTS inquiries (
  id   INTEGER PRIMARY KEY,
  ts   INTEGER NOT NULL,   -- unix seconds, UTC
  data TEXT    NOT NULL    -- JSON from SITE.logRow(): attribution only
);
CREATE INDEX IF NOT EXISTS inquiries_ts ON inquiries (ts);

CREATE TABLE IF NOT EXISTS events (
  id   INTEGER PRIMARY KEY,
  ts   INTEGER NOT NULL,
  name TEXT    NOT NULL,
  data TEXT    NOT NULL
);
CREATE INDEX IF NOT EXISTS events_name_ts ON events (name, ts);

CREATE TABLE IF NOT EXISTS hits (       -- rate-limit ledger
  ts      INTEGER NOT NULL,
  ip_hash TEXT    NOT NULL,          -- salted, truncated
  kind    TEXT    NOT NULL           -- 'contact' | 'event'
);
CREATE INDEX IF NOT EXISTS hits_lookup ON hits (ip_hash, kind, ts);

07 / What stays off Workers

Which sites should stay on the origin server?

08 / Operating the fleet

How do you monitor and publish many Workers static sites?

09 / Incident log

What broke during a 12-site Workers migration?

Every row is from the migration's git history. The general rule is the part to keep.

10 / Common mistakes

Common mistakes moving static sites to Workers

• Leaving forwarding Page Rules on a routed hostThey stop firing the moment the route exists, and parity cannot see it. Fix: convert to Single Redirects before cutover.
• Trusting html_handling for legacy URLsIt answers 307, and only for forms of files that exist. Slashless legacy URLs 404. Fix: explicit 301 lines for every variant with backlinks.
• Assuming _headers covers script responsesIt applies to assets only. A run_worker_first page ships without security headers. Fix: set them in code too.
• Leaving not_found_handling at its defaultnone returns a bare 404 with no page on an assets-only site. Fix: 404-page + 404.html.
• Deploying HTML before its form WorkerSubmissions 404 until the forms route exists. Fix: forms Worker first, or a service binding.
• Setting secrets on an upload-only Workerwrangler secret put refuses when the latest version is not deployed. Fix: wrangler versions secret put.
• Connecting Git buildsEvery push goes live and the human approval gate disappears. Fix: local guarded deploys; CI only for guarded data-only publishes.
• Publishing origin detailsOrigin IPs, SSH hosts, server paths, and account/zone/database ids in public docs let attackers bypass Cloudflare. Fix: placeholders; describe the origin generically.
• Believing a challenged parity runWhen Bot Fight Mode challenges most probes, "no differences" means nothing. Fix: treat more than max(5, 10%) challenged as exit 2.
• Blaming propagation firstVersion promotion is fast; a verifier that fails intermittently on big pages is more likely broken. Fix: test the checker against a known-good page.

11 / Sources

Sources

Cloudflare docs read 2026-09-28. Fleet repositories other than CheatSheets are private and cited as "fleet repository".

• Workers static assets overview: asset-only requests are free, default caching headers, not_found_handling modes.
• HTML handling: the four modes and their 307 redirects.
• Redirects: _redirects syntax, status codes, 200 rewrites, static-before-dynamic, limits.
• Headers: _headers syntax; not applied to Worker-generated responses.
• Static assets binding and configuration: run_worker_first patterns, binding, .assetsignore.
• Billing and limitations: free asset requests, 429 on over-quota script paths.
• Workers limits: 20,000 / 100,000 files, 25 MiB, _redirects and _headers caps, routes per zone.
• Workers pricing: $5 minimum, included requests, service binding billing.
• Versions and deployments: versions deploy does not apply triggers.
• Version URLs: alias format, 63-char limit, preview_urls default.
• Routes and Custom Domains: specificity, proxied-record requirement, CNAME conflict.
• Ruleset phases list: request-phase order with Single Redirects first.
• Workers with Page Rules: Forwarding URL ignored for requests to a Worker.
• Single Redirects and Page Rules migration: per-plan rule counts; Page Rules still available, migration recommended.
• Service bindings: private Workers reachable only by binding.
• D1 limits and R2 pricing; R2 public buckets: custom domain requirements.
• Turnstile server-side validation: siteverify parameters, 300 s single-use tokens.
• Wrangler commands: versions upload, versions deploy, triggers deploy (experimental), rollback, versions secret put.
• Migrate from Pages to Workers and the Pages overview ("Start new projects with Workers").
• This site's config and code, public: wrangler.jsonc, workers/site, workers/forms, scripts/deploy-cloudflare.sh, deploy/cloudflare/_headers.
• Fleet repository (private): the static-migration kit's runbook, deploy template, cf_parity.py, soak_check.py, fleet_check.py and contact-Worker template; each site's wrangler.jsonc, _redirects generator and forms Worker.

Related

Related Software & DevOps cheatsheets