Deploying to Cloudflare Pages

Cloudflare Pages offers incredible performance for static sites with their global edge network. This guide walks you through deployment.

Why Cloudflare Pages?

• Global CDN with 300+ locations
• Unlimited bandwidth on free tier
• Instant cache invalidation
• Built-in PR previews
• Custom domains with free SSL

Prerequisites

1. A GitHub or GitLab repository
2. A Cloudflare account (free tier works)
3. Your Astro project ready to deploy

Step 1: Connect Your Repository

1. Log in to Cloudflare Dashboard
2. Navigate to Pages → Create a project
3. Select Connect to Git
4. Authorize Cloudflare to access your repository
5. Select your Astro project repository

Step 2: Configure Build Settings

Setting	Value
Framework preset	Astro
Build command	npm run build
Build output directory	dist
Node version	20 (or higher)

Step 3: Environment Variables

Add your environment variables in the Settings → Environment variables section:

KEYSTATIC_STORAGE_KIND=cloud
KEYSTATIC_PROJECT=your-project-name
KEYSTATIC_CLOUD_ACCESS_TOKEN=your-token
PUBLIC_SITE_URL=https://your-site.pages.dev

Step 4: Deploy

Click Save and Deploy. Cloudflare will:

1. Pull your repository
2. Install dependencies
3. Run the build
4. Deploy to their edge network

First deployment typically takes 1-2 minutes.

Custom Domain Setup

1. Go to your project → Custom domains
2. Click Set up a custom domain
3. Enter your domain (e.g., www.yoursite.com)
4. Cloudflare will configure DNS automatically

Performance Tips

Enable Early Hints

Cloudflare supports 103 Early Hints for faster resource loading:

# wrangler.toml
[site]
bucket = "./dist"

Optimize Images

Use Cloudflare Images or ensure your images are optimized:

• WebP format with fallbacks
• Responsive srcset
• Lazy loading for below-fold images

Cache Headers

Static assets get aggressive caching automatically. For dynamic content:

Cache-Control: public, max-age=3600, stale-while-revalidate=86400

Continuous Deployment

Every push to your main branch triggers automatic deployment:

1. Push changes to GitHub
2. Cloudflare detects the push
3. New build starts automatically
4. Site updates when build completes

Preview Deployments

Pull requests get unique preview URLs:

https://abc123.your-site.pages.dev

Perfect for testing before merging.

Monitoring

Cloudflare provides:

• Analytics: Page views, bandwidth, visitors
• Web Analytics: Core Web Vitals, device breakdown
• Logs: Real-time request logs (paid plans)

Troubleshooting

Build Fails

Check the build logs. Common issues:

• Missing environment variables
• Node version mismatch
• Dependency resolution errors

404 on Routes

Ensure astro.config.mjs has correct site URL and output mode:

export default defineConfig({
  site: 'https://your-site.pages.dev',
  output: 'static',
});

Next Steps

Your site is now live on Cloudflare’s global network! Consider:

• Setting up a custom domain
• Configuring Cloudflare Analytics
• Adding Cloudflare Workers for dynamic features

Happy deploying!