Deploy to Cloudflare Pages

What Is Cloudflare Pages?

Cloudflare Pages is a static site hosting platform with a global CDN, free SSL, and automatic deployments from Git. It is the recommended hosting option for Astro Docus because:

• Free tier includes unlimited bandwidth and 500 builds per month
• Automatic deploys on every Git push
• Preview deployments for every pull request
• Custom domains supported on the free plan
• No credit card required to get started

This guide covers two methods:

1. GitHub Integration (recommended) — Cloudflare builds and deploys automatically
2. Direct Upload with Wrangler — deploy from your local machine without GitHub

---

Prerequisites

Before starting, you need:

• A Cloudflare account (free)
• Your Astro Docus project pushed to GitHub (see the previous guide)
• A terminal open in your project folder

---

Method 1 — Deploy via GitHub Integration

This is the recommended method. Once set up, every push to your main branch triggers an automatic build and deploy.

Step 1 — Sign Up or Log In to Cloudflare

1. Go to: https://dash.cloudflare.com/sign-up
2. Enter your email address and a password
3. Click Sign up
4. Verify your email by clicking the link Cloudflare sends you

If you already have an account, log in at: https://dash.cloudflare.com/login

Step 2 — Navigate to Pages

1. After logging in, look at the left sidebar
2. Click Workers & Pages
3. You are now on the Workers & Pages overview page

Step 3 — Create a New Pages Project

1. Click the Create application button
2. Select the Pages tab
3. Click Connect to Git

Step 4 — Connect Your GitHub Repository

1. Cloudflare prompts you to sign in with GitHub
2. Click Authorize Cloudflare Pages on the GitHub authorization page
3. You can choose to grant access to:
   • All repositories (easier, but broader access)
   • Only select repositories (recommended for security)
4. Select your Astro Docus repository from the list
5. Click Install & Authorize

Step 5 — Select the Repository

1. Cloudflare shows a list of your GitHub repositories
2. Click on your Astro Docus repository
3. Click Begin setup

Step 6 — Configure Build Settings

This is the most important step. Enter these exact values:

Configuration option	Value
Project name	astrodocus (or any name — becomes your *.pages.dev subdomain)
Production branch	main
Framework preset	Astro
Build command	npm run build
Build output directory	dist

These settings match the official Astro deployment guide .

Note: The Framework preset dropdown may auto-fill the build command and output directory. Verify they match the values above.

Step 7 — Deploy

1. Click Save and Deploy
2. Cloudflare starts building your site
3. You see a build log — this shows each step (installing dependencies, building, deploying)
4. First build takes 1–3 minutes
5. When complete, you see a success message and your live URL

Step 8 — Your Live Site

After deployment, you receive a unique URL:

https://astrodocus.pages.dev

(The exact subdomain depends on your project name.)

Open this URL in your browser. Your Astro Docus site is now live.

---

Method 2 — Direct Upload with Wrangler

Use this method if you do not want to connect GitHub. You build locally and upload the dist/ folder.

Step 1 — Install Wrangler

Wrangler is Cloudflare’s command-line tool.

npm install -g wrangler

Verify installation:

wrangler --version

Step 2 — Log In to Cloudflare

wrangler login

This opens your browser. Log in to Cloudflare and authorize Wrangler.

Step 3 — Build Your Site Locally

npm run build

This generates the dist/ folder with your static site.

Step 4 — Deploy to Cloudflare Pages

npx wrangler pages deploy dist

Wrangler uploads the contents of dist/ to Cloudflare Pages .

Step 5 — First-Time Setup

On first deploy, Wrangler asks:

• Project name: enter a name (e.g., astrodocus)
• Production branch: enter main

After that, the site is live at https://your-project.pages.dev.

Deploying Updates Later

Every time you want to update the live site:

npm run build
npx wrangler pages deploy dist

---

Adding a Custom Domain

A *.pages.dev subdomain works, but a custom domain looks more professional.

Step 1 — Go to Your Project

1. In the Cloudflare dashboard, go to Workers & Pages
2. Click your Pages project

Step 2 — Add Custom Domain

1. Click the Custom domains tab
2. Click Set up a custom domain
3. Enter your domain (e.g., docs.yourdomain.com)
4. Click Continue

Step 3 — Configure DNS

If your domain uses Cloudflare nameservers:

• Cloudflare adds the DNS record automatically
• Wait 1–2 minutes for propagation

If your domain is registered elsewhere:

• Cloudflare shows a CNAME record to add
• Go to your domain registrar (Namecheap, GoDaddy, etc.)
• Add a CNAME record pointing to your *.pages.dev URL
• Example: docs → astrodocus.pages.dev

Step 4 — Verify

After DNS propagates (5 minutes to 24 hours), your custom domain works with HTTPS automatically.

---

How Automatic Deployments Work

Once connected to GitHub, Cloudflare Pages watches your repository:

Action	Result
Push to main	Production deploy
Push to another branch	Preview deploy (unique URL)
Open a pull request	Preview deploy with PR comment

This means you never manually deploy again. Just git push, and Cloudflare handles the rest.

---

Understanding the Build Process

When Cloudflare builds your Astro Docus site:

1. Clones your repository
2. Installs dependencies (npm install)
3. Runs npm run build
4. Reads the dist/ folder
5. Deploys it to Cloudflare’s global network

The build log shows every step. If something fails, the log tells you exactly where.

---

Troubleshooting

Problem	Likely Cause	Fix
404 errors on *.pages.dev	Missing index.html at root	Check that dist/index.html exists
Build fails	Wrong Node version	Set NODE_VERSION environment variable
Build succeeds but site is blank	Wrong output directory	Verify dist is set correctly
Wrangler authentication fails	Token lacks Pages permission	Create API token with Cloudflare Pages: Edit scope
Custom domain not working	DNS not propagated	Wait longer, or check CNAME record
Slow build times	No cache	Cloudflare caches node_modules/.astro automatically for Astro

---

Environment Variables (Optional)

If your project needs environment variables (API keys, analytics tokens), set them in:

Cloudflare Dashboard → Your Pages project → Settings → Environment variables

Common variables for Astro Docus:

Variable	Value	Purpose
NODE_VERSION	20	Ensures correct Node.js version
CF_ANALYTICS_TOKEN	your token	Cloudflare Web Analytics

Set these before your first deploy if needed.

---

Quick Recap

Method 1 — GitHub Integration (recommended):
1. Sign up at cloudflare.com
2. Workers & Pages → Create application → Pages
3. Connect to Git → Authorize GitHub
4. Select your Astro Docus repository
5. Build settings:
   - Build command: npm run build
   - Output directory: dist
6. Save and Deploy
7. Your site is live at *.pages.dev

Method 2 — Wrangler Direct Upload:
1. npm install -g wrangler
2. wrangler login
3. npm run build
4. npx wrangler pages deploy dist
5. Live at *.pages.dev

Custom Domain:
- Dashboard → Your project → Custom domains
- Add domain → Configure DNS
- HTTPS automatic

Cloudflare Pages is free, fast, and automatic. Once connected to GitHub, every git push deploys your site globally in under two minutes.

👉 Next: docs/deploy-hosting/vercel.md — deploy to Vercel.