cloudflare-pages-static-site

name	cloudflare-pages-static-site
description	Deploy single-page static sites to Cloudflare via Workers static assets (current dashboard flow, not the deprecated Pages Connect-to-Git flow) with custom domains. No framework, no build step. Trigger keywords: static site, Cloudflare Pages, Cloudflare Workers, landing page, deploy website, custom domain, pages.dev, workers.dev, wrangler.
license	MIT
metadata	{"version":"2.0.0","hermes":{"tags":["Cloudflare","Deployment","Static-sites","Frontend","Workers"],"related_skills":["static-html-app-development"]}}

Deploying Static Sites to Cloudflare (Workers static assets)

Ship static HTML/CSS with custom domain in under an hour.

Cloudflare's dashboard as of 2026-07 routes new static sites through Workers static assets (wrangler deploy), not the older "Pages tab → Connect to Git → Framework: None" flow — that classic flow may still work for existing Pages projects, but "Create application" no longer surfaces it as the default path for a new one. Don't assume the old flow when working from memory; verify against the live dashboard, since Cloudflare has been consolidating Pages into Workers.

Workflow

1. Create repo: mkdir -p ~/src/<site>/public && cd ~/src/<site> && git init
2. Write files into public/: public/index.html + public/style.css (no framework for single-page sites) — do not put them at the repo root (see Pitfalls)
3. Add wrangler.jsonc at the repo root:

   {
     "name": "<site>",
     "compatibility_date": "YYYY-MM-DD",  // today's date
     "assets": { "directory": "./public" }
   }
   

4. Verify before touching Cloudflare — dry-run the actual deploy tool locally: npx wrangler deploy --dry-run --outdir /tmp/dry-run. It should report Read N files from the assets directory .../public where N matches exactly your public files (e.g. 2 for index.html + style.css). If it reports far more, something outside public/ is leaking in — check assets.directory isn't pointing at . (repo root).
5. Push to GitHub: gh repo create <site> --public --source=. --push
6. Cloudflare dashboard: Workers & Pages → Create application → Workers → Connect to Git → select repo. Build command: leave empty. Deploy command: npx wrangler deploy (prefilled default — correct, it reads your wrangler.jsonc).
7. Custom domain: Worker project → Settings → Domains & Routes → add domain. Add CNAME in DNS if not auto-added.
8. Iterate: Every git push auto-deploys in ~30-60 seconds — but note Cloudflare's own GitHub App may also open a PR proposing its own wrangler.jsonc (see Pitfalls) shortly after you connect the repo.

DNS Setup

• Delete old A records pointing to previous host
• Add CNAME: @ (or subdomain) → <project>.workers.dev (or <project>.pages.dev if still on classic Pages)
• For www: add as a custom domain on the project AND add www CNAME in DNS (both required)
• Don't use wildcard (*) CNAME — causes 522 errors on undefined subdomains

Domain transfer: Change nameservers to Cloudflare's NS at old registrar, enter auth/EPP code at Cloudflare, ~$10/year at cost.

Anti-Patterns

• Over-engineering v1: Single-page site doesn't need React/Tailwind/CMS. index.html + style.css ships in 30 minutes.

Pitfalls

• assets.directory: "." (repo root) publicly serves the WHOLE repo — scripts, README, .github/ workflow files, .git/, everything, not just the intended page. Confirmed 2026-07-12: a dry-run against a bare repo root read 150 files (including .git/ objects); scoping assets.directory to a dedicated ./public subdirectory containing only the real deployable files brought it down to exactly 2. Isolate deployable files into their own subdirectory from the start — don't rely on a .assetsignore exclude-list, which is easy to get subtly wrong (e.g. forgetting .git/ itself needs excluding) and harder to verify at a glance than "this directory contains only what should be public."
• Cloudflare's GitHub App auto-opens its own config PR (branch cloudflare/workers-autoconfig, commit "Add Cloudflare Workers configuration", authored by cloudflare-workers-and-pages[bot]) shortly after you connect a repo — and its auto-generated wrangler.jsonc defaults to assets.directory: "." (unscoped repo root), which is exactly the unsafe pattern above. If you've already set up a properly-scoped config, do not merge this PR — it will silently regress your fix. Check gh pr list after connecting a repo; close it with an explanatory comment if found.
• git add pathA pathB where one path doesn't exist on disk aborts the ENTIRE add, silently, for every path in the call — not just the invalid one. Hit this after a git mv old new: a single git add old new otherfile1 otherfile2 failed with fatal: pathspec 'old' did not match any files because old no longer exists post-rename, and NONE of the paths (including the valid, unrelated otherfile1/otherfile2) got staged. The failure looked like a no-op rather than an error, and a subsequent bare git commit silently committed less than intended. Always run git show --stat HEAD after committing a batch that included any move/rename to confirm the full intended file list actually landed — don't trust that a git add with multiple paths staged everything just because the command didn't visibly explode.