LLM Best Practices

How to deploy a static site to Cloudflare

Last updated 4 min read

View markdown source

AI agents: read this first: llmbestpractices.com/start-here

This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work.

  1. Route, do not crawl. Fetch llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
  2. Read raw. Append .md to any page URL for markdown. Check status and last_updated in the frontmatter, then read the rules.
  3. Apply as defaults. First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
  4. Cite. Link the page by title and URL, e.g. Python, with last_updated for time-sensitive rules. License CC BY 4.0.

Overview

Start new Cloudflare static sites on Workers with static assets; Cloudflare’s docs say to start new projects on Workers and keep Pages for existing ones. A Worker with an assets.directory serves the build output, and Workers Builds redeploys on every push. Pages is not deprecated, so the Pages settings are listed at the end for projects already on it.

Prerequisites

  • A Cloudflare account and a GitHub repo containing the site. For Quartz 4, clone -b v4 and set up the repo as in steps 1 and 2 of deploy-quartz-site; it builds with npx quartz build to public/.
  • Node pinned for the build: add a .node-version or .nvmrc file, or set a NODE_VERSION build variable.
  • A domain whose DNS is on Cloudflare (needed for Custom Domains on a Worker).

Steps

1. Add wrangler.jsonc at the repo root

{
  "name": "my-site",
  "compatibility_date": "2026-10-01",
  "assets": { "directory": "./public" }
}

The name must match the Worker name in the dashboard, or the build fails. For a Quartz site, set baseUrl to the production domain in quartz.config.ts; Plugin.CNAME() is only for GitHub Pages and can stay or go.

2. Connect the repo with Workers Builds

In the dashboard open Workers & Pages, create a Worker from a Git repository, and set:

  • Build command: npx quartz build
  • Deploy command: npx wrangler deploy (the default)

Quartz reads git history for dates, and CI clones can be shallow; if dates collapse to the build date, make the build command git fetch --unshallow && npx quartz build.

3. Add the custom domain

On the Worker, open Settings, Domains & Routes, Add, Custom Domain. Cloudflare issues the certificate. A hostname that already has a CNAME record cannot become a Custom Domain, so delete the old record first. In code, the equivalent is:

{ "routes": [{ "pattern": "yourdomain.com", "custom_domain": true }] }

4. Existing Pages projects

Settings for Pages: Framework preset None, build command npx quartz build, output directory public, production branch main, plus NODE_VERSION or a .node-version file. See Cloudflare’s “migrate from Pages to Workers” guide to move: pages_build_output_dir becomes assets.directory, and wrangler pages deploy becomes wrangler deploy.

Verify it worked

curl -sI https://yourdomain.com | head -1          # HTTP/2 200
curl -sI https://yourdomain.com | grep -i '^cf-ray' # served through Cloudflare

Common errors

  • Build fails on Node version. Pin it with .node-version or NODE_VERSION; the default differs between Workers Builds and Pages build images.
  • 404 for unknown URLs shows the wrong page. Set assets.not_found_handling to "404-page" (serves 404.html) or "single-page-application" (serves index.html with 200).
  • Build fails with a name mismatch. The name in wrangler.jsonc differs from the Worker’s name in the dashboard.
  • Links point at the wrong host. baseUrl still holds the old domain; fix it and rebuild.

FAQ

Should I use Cloudflare Pages or Workers for a new static site?

Use Workers with static assets. Cloudflare’s docs say to start new projects on Workers and keep Pages for existing ones; Pages is not deprecated.

Why does my Workers build fail with a name mismatch?

The name in wrangler.jsonc differs from the Worker’s name in the dashboard; make them match.

Why can I not add my hostname as a Custom Domain?

A hostname that already has a CNAME record cannot become a Custom Domain, so delete the old record first.

Why do my Quartz page dates all show the build date on Cloudflare?

Quartz reads git history for dates and CI clones can be shallow; make the build command git fetch --unshallow && npx quartz build.

How do I move an existing site from Pages to Workers?

Follow Cloudflare’s “migrate from Pages to Workers” guide: pages_build_output_dir becomes assets.directory, and wrangler pages deploy becomes wrangler deploy.

Backlinks