How to Deploy Your Astro Site to Cloudflare Pages (2026)

Astro and Cloudflare Pages are an excellent match. Astro’s static output mode generates pure HTML, CSS, and JavaScript — exactly what Cloudflare Pages is optimized to serve. You get unlimited bandwidth, 500 free builds/month, and global CDN distribution at zero cost.

This guide walks through deploying an Astro site to Cloudflare Pages from scratch.

Prerequisites

An Astro project (local or on GitHub)
A Cloudflare account (free at cloudflare.com)
Node.js 18+ installed locally

Option 1: Static Output (Recommended for Most Sites)

For blogs, portfolios, documentation, and marketing sites, Astro’s static output mode is the best choice with Cloudflare Pages.

Step 1: Configure Astro for Static Output

In your astro.config.mjs:

import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static',
  // No adapter needed for pure static
});

Step 2: Build and Verify Locally

npx astro build
# Output goes to dist/ directory

Open dist/index.html in a browser to verify your build looks correct.

Step 3: Push to GitHub

git add .
git commit -m "Ready for Cloudflare Pages deployment"
git push origin main

Step 4: Connect to Cloudflare Pages

Log into Cloudflare dashboard
Click Workers & Pages → Create application → Pages
Click Connect to Git → authorize GitHub
Select your repository
Configure the build:
- Framework preset: Astro
- Build command: npx astro build
- Build output directory: dist
Click Save and Deploy

Cloudflare detects Astro automatically and pre-fills the settings. Your site deploys in 1–3 minutes.

Step 5: Get Your Site URL

Cloudflare assigns a *.pages.dev URL immediately. Visit it to verify your site.

Option 2: Server-Side Rendering with Cloudflare Workers

For Astro sites with dynamic routes, API endpoints, or server-side rendering, use the Cloudflare adapter.

Install the Adapter

npx astro add cloudflare

This installs @astrojs/cloudflare and updates astro.config.mjs:

import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare(),
});

Important: Node.js Compatibility

If you’re using Node 24 (or encountering require_dist is not a function errors), add this to wrangler.toml:

compatibility_flags = ["nodejs_compat"]

Or add to your Cloudflare Pages settings: Settings → Functions → Compatibility flags → add nodejs_compat.

Build and Deploy

The deployment process is identical to static — push to GitHub, Cloudflare builds and deploys automatically.

Adding a Custom Domain

In your Pages project, click Custom domains
Enter your domain (e.g., yourdomain.com)
If your domain’s DNS is on Cloudflare: automatically configured
If your domain is elsewhere: add a CNAME record pointing to your-project.pages.dev

SSL certificate is automatically provisioned — no configuration needed.

Environment Variables

For Astro sites with API keys or configuration:

Go to your Pages project → Settings → Environment variables
Add variables for Production and optionally Preview
Access them in your Astro code:

// Works in SSR mode
const apiKey = import.meta.env.MY_API_KEY;

// For build-time variables (static mode), prefix with PUBLIC_
const publicKey = import.meta.env.PUBLIC_SITE_URL;

Preview Deployments

Every pull request to your repository automatically gets a preview deployment at a unique *.pages.dev URL. Share this link with stakeholders for review before merging.

To disable preview deployments: Settings → Builds & deployments → Branch control.

Performance Optimization

Enable Cloudflare CDN Features

Since your site is on Cloudflare, these features activate automatically:

Auto Minify: Minifies HTML, CSS, JS — enable under Speed → Optimization
Brotli Compression: Enabled by default
HTTP/3: Enabled by default

Purge Cache on Deploy

Cloudflare Pages automatically purges the CDN cache on each deployment — no manual action required.

Using Cloudflare R2 for Assets

For large media files (images, videos), store them in Cloudflare R2 to avoid bandwidth costs:

// In astro.config.mjs, set your base URL
export default defineConfig({
  image: {
    domains: ['your-r2-bucket.r2.cloudflarestorage.com'],
  },
});

Troubleshooting Common Issues

Build Fails: Module Not Found

Error: Cannot find module 'xyz'

Add a package.json engines field or check your Node.js version:

Cloudflare Pages default Node.js: 18
To use Node 20: Add environment variable NODE_VERSION=20

Static Site Shows Old Version

Cloudflare CDN caches aggressively. If you see a stale version after deploy:

Go to Caching → Cache Rules → Purge Everything (temporary fix)
Or use Cache-Control: no-store headers for dynamic content

SSR Routes Not Working

For SSR mode, ensure compatibility_flags = ["nodejs_compat"] is set and you’re using the server output mode, not static.

If you’re using Astro with React/Vue client-side routing, configure your _redirects file:

/* /index.html 200

Place this in your public/ directory.

Connecting Cloudflare Workers for API Routes

If your Astro app needs serverless API routes without full SSR:

// src/pages/api/hello.js
export async function GET({ request }) {
  return new Response(JSON.stringify({ message: "Hello from Cloudflare!" }), {
    headers: { 'Content-Type': 'application/json' }
  });
}

In SSR mode, these API routes run as Cloudflare Workers automatically.

Summary: Astro + Cloudflare Pages Workflow

Develop locally with npx astro dev
Push to GitHub when ready
Cloudflare Pages builds automatically
Preview URL appears for each PR
Merge to main → production deploys
Custom domain with automatic SSL

The combination delivers professional-grade deployment infrastructure for free. No credit card, no server management, and unlimited bandwidth.

Get started with Cloudflare Pages free — connect your GitHub repo in under 5 minutes.

For performance-critical Next.js applications, Vercel is worth comparing as an alternative.

How to Deploy Your Astro Site to Cloudflare Pages (2026)