Deploy Your Astro Project to Cloudflare Pages

This is how you can deploy your Astro project to Cloudflare Pages using Wrangler. You can also use this guide to deploy any static site to Cloudflare Pages, just adjust the build commands and output directory as needed.

Creating Your Astro Project

First, create a new Astro project or choose from the themes available at astro.build/themes. Follow the installation instructions provided by your chosen theme.

Useful Astro Integrations

After exploring the official integrations page, I found these most useful for my Astro projects:

Framework Integrations

You can add popular JavaScript frameworks like React, Vue, Svelte, or SolidJS to your Astro project. These components work as islands, only hydrating when needed for optimal performance. Check out the official integrations page for the complete list.

Content & Styling

For content, @astrojs/mdx lets you embed interactive components directly in markdown content. @astrojs/tailwind is good for CSS. For code highlighting, astro-expressive-code gives syntax highlighting and the code sections you in this blog. astro-embed provides easy-to-use components for embedding social media posts, videos, and other external content.

Performance & SEO

You can use @playform/compress to automatically compress HTML, CSS, and JavaScript files. @astrojs/sitemap generates XML sitemaps for better SEO. I use Astro Assets for built-in image optimization with format conversion, It will auto generate various image of various sizes automatically if you create the srcsets.

Documentation Sites

For documentation sites, @astrojs/starlight is pretty good - it’s a documentation theme built on Astro with search, navigation, and internationalization built in.

Install Integrations

# Example: Adding React and Tailwind
npx astro add react tailwind

# Or install manually
npm install @astrojs/react @astrojs/tailwind

Setting Up Cloudflare Deployment

1. Install Wrangler

Add Wrangler to your project dependencies:

npm install wrangler

Update your package.json scripts (replace astro build with your framework’s build command):

{
  "scripts": {
    "build": "astro build",
    "deploy": "astro build && wrangler deploy"
  }
}

2. Create wrangler.json

Create a wrangler.json file in your project root:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-astro-site",
  "compatibility_date": "2025-09-21",
  "assets": {
    "directory": "./dist"
  },
  "observability": {
    "enabled": true
  }
}

Configuration Options

• name: Your Cloudflare Pages project name (will be used in the URL)
• compatibility_date: Ensures your worker uses the correct runtime features (use today’s date). Later if it won’t break if cloudflare updates their runtime, for static sites it’s not a big deal.
• assets.directory: Points to your build output folder (./dist for Astro)
• observability: Enables analytics and logging in Cloudflare dashboard

Deploying to Cloudflare

First-Time Deployment

1. Build your project:

npm run build

2. Deploy to Cloudflare:

npm run deploy

3. Authentication: Wrangler will open your browser and ask you to log in to Cloudflare
4. Project Creation: A new Cloudflare worker will be created with the name from your wrangler.json
5. Deployment: Your site will be deployed and you’ll get a .workers.dev URL

Subsequent Deployments

For future deployments, simply run:

npm run deploy

Custom Domain Setup

1. Go to your Cloudflare Dashboard
2. Navigate to Compute → Workers & Pages
3. Select your worker
4. Go to Settings → Domains & Routes
5. Click “Set up a custom domain”
6. Add your domain and follow the DNS configuration steps
7. Cloudflare will automatically provision an SSL certificate

Your Astro site is now live on Cloudflare’s global edge network with automatic SSL, CDN, and lightning-fast performance!