Skip to content

Deploying to Cloudflare Pages

Deploy your site to Cloudflare's global edge network.

Why Cloudflare Pages?

  • Global Edge Network: 300+ locations worldwide
  • Zero Configuration: Auto-detects Astro
  • Unlimited Bandwidth: No bandwidth limits on free tier
  • Preview Deployments: Every branch gets a URL
  • Built-in Analytics: Free Web Analytics
  • Edge Functions: Serverless functions at the edge

Prerequisites

  • Cloudflare account (free tier works)
  • GitHub repository
  • Repository pushed to GitHub

Setup via Dashboard

1. Connect Repository

  1. Log in to Cloudflare Dashboard
  2. Go to Workers & Pages → Create application
  3. Select Pages → Connect to Git
  4. Authorize Cloudflare to access your GitHub account
  5. Select your repository: chrislyons-dev/home

2. Configure Build

Cloudflare auto-detects Astro, but verify these settings:

Build Configuration:

  • Framework preset: Astro
  • Build command: npm run build
  • Build output directory: dist
  • Root directory: / (default)
  • Node version: 20

Environment Variables:

PUBLIC_SITE_URL=https://chrislyons.dev

3. Deploy

  1. Click Save and Deploy
  2. Wait 2-3 minutes for initial build
  3. Your site will be live at https://chrislyons-dev.pages.dev

Branch Deployments

Production Branch

Set your production branch in project settings:

  1. Settings → Builds & deployments
  2. Production branch: main
  3. Every push to main deploys to production

Preview Branches

All other branches automatically get preview URLs:

# Create feature branch
git checkout -b feature/new-feature
git push origin feature/new-feature

Preview URL: https://[commit-hash].chrislyons-dev.pages.dev

Branch-Specific Deployments

Configure which branches trigger deployments:

  1. Settings → Builds & deployments
  2. Branch deployments
  3. Add branches:
  4. main → Production
  5. staging → Staging environment
  6. develop → Development preview

Setup via GitHub Actions

For more control, use the GitHub Actions workflow.

1. Get Cloudflare Credentials

API Token:

  1. Cloudflare Dashboard → My Profile → API Tokens
  2. Click Create Token
  3. Use template: Edit Cloudflare Workers
  4. Copy the token

Account ID:

  1. Cloudflare Dashboard → Workers & Pages
  2. Copy Account ID from the right sidebar

2. Add GitHub Secrets

  1. GitHub Repository → Settings → Secrets and variables → Actions
  2. Click New repository secret
  3. Add:
  4. Name: CLOUDFLARE_API_TOKEN
  5. Value: [your API token]
  6. Add:
  7. Name: CLOUDFLARE_ACCOUNT_ID
  8. Value: [your account ID]

3. Workflow Configuration

The workflow in .github/workflows/cloudflare.yml handles deployment:

on:
  push:
    branches:
      - main # Production
      - staging # Staging environment
      - develop # Development preview

Customize branches by editing the workflow file.

4. Deploy

git add .
git commit -m "feat: configure Cloudflare Pages"
git push origin main

GitHub Actions will build and deploy automatically.

Custom Domain

Add Custom Domain

  1. Custom domains → Set up a custom domain
  2. Enter your domain: chrislyons.dev
  3. Choose setup method:

Option A: Cloudflare-managed DNS

  1. Domain already on Cloudflare
  2. Click Activate domain
  3. DNS records added automatically

Option B: External DNS

  1. Add CNAME record: 
    Type: CNAME
Name: @
Value: chrislyons-dev.pages.dev
  2. For apex domain, use CNAME flattening or ALIAS record

SSL/TLS

SSL certificates are automatically provisioned:

  • Universal SSL (default)
  • Auto-renewal every 90 days
  • Full (strict) encryption mode recommended

Environment Variables

Add Variables

  1. Settings → Environment variables
  2. Click Add variable
  3. Set per environment:
  4. Production: main branch
  5. Preview: All other branches

Example:

PUBLIC_SITE_URL
  Production: https://chrislyons.dev
  Preview: https://preview.chrislyons.dev

Access in Code

const siteUrl = import.meta.env.PUBLIC_SITE_URL;

Build Configuration

Custom Build Command

Override default build in Settings → Builds & deployments:

# Install dependencies and build
npm ci && npm run build

# Run tests before build
npm ci && npm test && npm run build

Build Watch Paths

Trigger builds only on specific file changes:

  1. Settings → Builds & deployments
  2. Build watch paths
  3. Add patterns: 
    src/**
public/**
astro.config.mjs
package.json

Performance

Edge Caching

Cloudflare automatically caches:

  • Static assets: 1 year
  • HTML: Configurable
  • Images: Auto-optimized

Headers Configuration

Set in wrangler.toml:

[[headers]]
for = "/*"
  [headers.values]
  Cache-Control = "public, max-age=3600"

Compression

Auto-enabled:

  • Brotli compression
  • Gzip fallback
  • Smart compression

Analytics

Enable Web Analytics

  1. Analytics → Web Analytics
  2. Enable for your domain
  3. View metrics:
  4. Page views
  5. Unique visitors
  6. Geographic distribution
  7. Performance metrics

Custom Events

Add to your site:

<script
  defer
  src="https://static.cloudflareinsights.com/beacon.min.js"
  data-cf-beacon='{"token": "your-token"}'
></script>

Functions (Optional)

Add Edge Functions

Create functions/ directory:

// functions/api/hello.ts
export const onRequest: PagesFunction = async (context) => {
  return new Response('Hello from the edge!');
};

Available at: /api/hello

Rollback

Revert to Previous Deployment

  1. Deployments tab
  2. Find last good deployment
  3. Click ⋯ → Rollback to this deployment
  4. Confirm rollback

Via Git

git revert <commit-hash>
git push origin main

Monitoring

Deployment Status

View in real-time:

  • Deployments tab
  • Build logs
  • Deployment timeline

Error Logs

  1. Functions → Logs (if using functions)
  2. Real-time error tracking
  3. Filter by severity

Troubleshooting

Build Failures

Check build logs:

  1. Go to failed deployment
  2. View Build log
  3. Look for errors

Common issues:

Node version mismatch:

# In build settings
Environment variable: NODE_VERSION=20

Missing dependencies:

# Ensure package-lock.json is committed
git add package-lock.json
git commit -m "fix: add lock file"

Deployment Not Updating

  1. Clear build cache:
  2. Settings → Builds & deployments

  3. Clear cache and retry

  4. Force rebuild: 

    git commit --allow-empty -m "chore: trigger rebuild"
git push

Custom Domain Issues

CNAME not resolving:

  • Wait for DNS propagation (up to 48 hours)
  • Verify DNS records: dig chrislyons.dev
  • Check Cloudflare DNS settings

SSL errors:

  • Ensure SSL/TLS mode is Full (strict)
  • Wait for certificate provisioning
  • Check SSL/TLS → Edge Certificates

CI/CD Integration

GitHub Actions + Cloudflare

Full workflow in .github/workflows/cloudflare.yml:

- name: Deploy to Cloudflare Pages
  uses: cloudflare/pages-action@v1
  with:
    apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
    projectName: chrislyons-dev
    directory: dist
    branch: ${{ github.ref_name }}

Cost

Free Tier

Includes:

  • Unlimited requests
  • Unlimited bandwidth
  • 500 builds/month
  • 20,000 functions requests/day (if using functions)

Pro Tier ($20/month)

Adds:

  • 5,000 builds/month
  • Advanced DDoS protection
  • Faster builds
  • Priority support

Comparison with Other Platforms

Feature Cloudflare Vercel Netlify
Bandwidth Unlimited 100GB 100GB
Build minutes 500/mo 6,000/mo 300/mo
Edge locations 300+ 100+ 100+
Functions Yes (free) Yes (paid) Yes (125k/mo)
Analytics Free Paid Paid

Next Steps