cloudflare-pages

Cloudflare Pages

Deploy any static site to Cloudflare Pages — create projects, attach custom domains, wire up CI/CD, and verify deployments. Framework-agnostic: works with Hugo, Astro, Next.js, Nuxt, SvelteKit, or any build tool that produces static output.

Prerequisites

Requirement	How to get it
wrangler CLI	npm i -g wrangler then wrangler login (opens browser OAuth)
Cloudflare account	dash.cloudflare.com — free tier works
Account ID	Dashboard → any zone → Overview sidebar, or wrangler whoami
API Token (CI/CD)	Dashboard → API Tokens → "Edit Cloudflare Workers" template (includes Pages)
DNS API Token	Dashboard → API Tokens → Custom → Zone:DNS:Edit (only if adding custom domains via API)
Zone ID	Dashboard → your domain → Overview sidebar (only for custom domains)

Quick Deploy

For a one-off manual deploy when CI/CD isn't set up yet:

# 1. Build your site
<your-build-command>          # e.g. hugo --minify, npm run build

# 2. Deploy output directory
wrangler pages deploy <output-dir> --project-name <project-name>

Each deploy gets a unique preview URL. The latest deploy on production branch becomes the live site at <project>.pages.dev.

Full Setup Workflow

Step 1 — Create the Pages project

bash scripts/setup-pages-project.sh <project-name> "<build-command>" <output-dir> [branch]

This runs wrangler pages project create and prints the resulting *.pages.dev URL. The branch argument defaults to main.

Manual alternative:

wrangler pages project create <project-name> --production-branch main

Step 2 — Deploy

Build and deploy:

<your-build-command>
wrangler pages deploy <output-dir> --project-name <project-name>

Step 3 — Add a custom domain

# Set required environment variables
export CLOUDFLARE_ACCOUNT_ID="<your-account-id>"
export CLOUDFLARE_API_TOKEN="<pages-edit-token>"
export CLOUDFLARE_ZONE_ID="<your-zone-id>"
export CLOUDFLARE_DNS_TOKEN="<dns-edit-token>"   # optional, falls back to API_TOKEN

bash scripts/add-custom-domain.sh <custom-domain> <project-name>

The script performs two operations:

1. Registers the domain on the Pages project via Cloudflare API
2. Creates a proxied CNAME DNS record pointing to <project>.pages.dev

Both operations are idempotent — safe to re-run.

Step 4 — Set up CI/CD

See references/ci-cd-templates.md for complete GitHub Actions workflows for Hugo, Astro, Next.js, and generic npm builds.

Required GitHub Secrets:

Secret	Value
CLOUDFLARE_API_TOKEN	API token with "Edit Cloudflare Workers" permissions
CLOUDFLARE_ACCOUNT_ID	Your Cloudflare account ID

Set these at: Repository → Settings → Secrets and variables → Actions → New repository secret

Rollback

# List recent deployments
wrangler pages deployment list --project-name <project-name>

# Rollback: checkout previous commit, rebuild, redeploy
git checkout <commit-hash>
<your-build-command>
wrangler pages deploy <output-dir> --project-name <project-name>

# Return to latest
git checkout main

Verify Deployment

export CLOUDFLARE_ACCOUNT_ID="<your-account-id>"
export CLOUDFLARE_API_TOKEN="<your-token>"

bash scripts/verify-deployment.sh <project-name> [custom-domain]

Shows: latest deployment status (color-coded), last 5 deployments table, custom domain SSL status, and HTTP 200 check on *.pages.dev.

Script Reference

Script	Purpose	Required env vars
setup-pages-project.sh	Create Pages project via wrangler	CLOUDFLARE_ACCOUNT_ID
add-custom-domain.sh	Register domain + create CNAME	CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN, CLOUDFLARE_ZONE_ID
verify-deployment.sh	Check deploy status, SSL, HTTP	CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN

Token Reference

Operation	Token needed	Scope	Where used
wrangler pages deploy	Wrangler OAuth	Automatic via wrangler login	Local CLI, CI/CD
Register custom domain on Pages	API Token	Account:Cloudflare Pages:Edit	add-custom-domain.sh
Create CNAME DNS record	DNS API Token	Zone:DNS:Edit	add-custom-domain.sh
CI/CD deploy (GitHub Actions)	API Token	"Edit Cloudflare Workers" template	GitHub Secrets
Query deployments	API Token	Account:Cloudflare Pages:Read	verify-deployment.sh

Tip: For simpler setups, a single API token with both Pages:Edit and DNS:Edit scopes can be used — set CLOUDFLARE_API_TOKEN and omit CLOUDFLARE_DNS_TOKEN.

Troubleshooting

Problem	Cause	Fix
wrangler: command not found	wrangler not installed	npm i -g wrangler
Authentication error	OAuth expired or wrong token	wrangler login (re-authenticate)
Custom domain stuck "pending"	Missing or wrong CNAME record	Check DNS: CNAME must point to <project>.pages.dev
SSL not provisioning	Domain not proxied through Cloudflare	Set CNAME proxy to "Proxied" (orange cloud)
522 error on custom domain	DNS record exists but wrong target	Delete old record, re-run add-custom-domain.sh
Deploy succeeds but site 404s	Wrong output directory	Verify build output dir matches deploy path
CI/CD deploy fails	Missing GitHub secrets	Add CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID

Agentic Workflow & Vibe Coding

• Iterative Deployment: Do not expect the perfect CI/CD setup or DNS propagation on the first run. Draft the configuration or run the manual deploy, review the Cloudflare Pages logs or status checks, isolate specific build errors or proxy issues, adjust ONE setting at a time, and redeploy until the site is live.
• Vibe Coding: Commit your working deployment scripts and GitHub Actions workflows locally before testing them on the live repository, making it easy to roll back if the pipeline breaks.

Anti-Patterns

• Don't use Cloudflare's git integration — use wrangler pages deploy for direct uploads. Git integration adds complexity with no benefit for this workflow.
• Don't create multiple projects for the same site — one project can have multiple custom domains.
• Don't skip the CNAME step — registering a domain on Pages without the DNS record leaves it "pending" indefinitely.
• Don't use unproxied CNAME records — Cloudflare's SSL and CDN only work when the orange cloud (proxy) is enabled.
• Don't hardcode account IDs in scripts — always use environment variables.