LLM Best Practices

How to deploy a static site to Cloudflare Pages

3 min read

View markdown source

Overview

Cloudflare Pages deploys static sites from a GitHub or GitLab repository, runs a build command on every push, and serves the output globally from Cloudflare’s CDN. This guide covers connecting a repository, setting environment variables, pointing a custom domain, and verifying the deployment. For the Quartz-specific path, see set-up-quartz-with-cloudflare-pages.

Prerequisites

  • A Cloudflare account with Pages enabled.
  • A GitHub repository containing the static site source. The repository must be accessible by your Cloudflare account.
  • The site’s build command and output directory. Examples: npm run build and dist for Vite; npx quartz build and public for Quartz.
  • A custom domain in Cloudflare DNS, if applicable.

Steps

1. Create a new Pages project

  1. Log in to the Cloudflare dashboard.
  2. Navigate to Workers and Pages > Pages > Create a project.
  3. Select Connect to Git and authorize Cloudflare to read your GitHub organization and repositories.
  4. Choose the repository and click Begin setup.

2. Configure build settings

Set the build configuration on the setup screen.

FieldExample value
Framework presetNone (or select if applicable)
Build commandnpm run build
Build output directorydist
Root directory/ (unless monorepo)
Node.js version22 (set in environment variables as NODE_VERSION=22)

For a Quartz 4 site:

Build command: npx quartz build
Build output directory: public

3. Set environment variables

Expand Environment variables during setup or add them later in Settings > Environment variables.

NODE_VERSION = 22

Add secrets (API keys, tokens) as encrypted environment variables. They are not exposed in build logs.

4. Deploy

Click Save and Deploy. Cloudflare Pages clones the repository, runs the build command, and publishes the output directory. The first deployment takes one to two minutes. Subsequent deployments are faster due to caching.

The project page shows the deployment URL: https://<project-name>.pages.dev.

5. Add a custom domain

  1. In the Pages project, go to Custom domains > Set up a custom domain.
  2. Enter the domain (example.com or www.example.com).
  3. Cloudflare automatically creates a CNAME record if the domain is on the same Cloudflare account. For external DNS, add a CNAME pointing to <project-name>.pages.dev.
  4. SSL is provisioned automatically via Cloudflare’s certificate authority.

6. Configure branch deployments (optional)

Pages deploys every push to the production branch (usually main) as a production deployment, and every other branch as a preview deployment at a unique URL. Preview deployments share the same build settings but do not update the custom domain.

To skip preview builds for noisy branches, add a branch exclusion in Settings > Builds and deployments.

Verify it worked

# Check the live deployment
curl -I https://your-domain.com
# Expect: HTTP/2 200 and CF-Ray header confirming Cloudflare served it
 
# Check deployment status via Wrangler CLI
npx wrangler pages deployment list --project-name your-project-name

The Cloudflare dashboard shows the latest deployment status, build time, and a link to the deployment log.

Common errors

  • Build fails with “Node version not supported”: set NODE_VERSION=22 in environment variables. Cloudflare Pages defaults to Node 18.
  • Output directory not found: the build command succeeded but the output directory name does not match. Check the exact name (dist, public, out, _site) in the build command docs.
  • Custom domain not serving: the CNAME record may not have propagated yet. Check with dig your-domain.com CNAME. If on a different DNS provider, TTL may delay propagation up to 24 hours.
  • Environment variable not available during build: variables set in the Cloudflare dashboard are available as process environment variables during the build. Confirm the name matches exactly (case-sensitive).
  • Pages quota exceeded: the free plan allows 500 deployments per month. For high-frequency deployments, consider Cloudflare Workers or upgrade the plan.

Graph View