Easy steps to deploy Astro sites to the world!

Astro is a rising-star web framework for building fast, content-driven websites. If you're reading this, chances are you've just finished building your new Astro site. The next crucial step is deploying it to the world! That's where Cloudflare Pages comes in, providing a simple path from your development environment to a live, globally-distributed site.

In this tutorial, we'll guide you through the process of deploying your Astro site to Cloudflare Pages. Whether you're a beginner or looking to migrate your existing website to Astro, this guide will help you get your site running quickly and easily.

Why Choose Cloudflare Pages for Your Astro Site?

Cloudflare Pages is a platform that lets you build and deploy static websites or JAMstack applications. It offers several key benefits for hosting Astro sites:

Git integration: You can connect your GitHub or GitLab directly to Cloudflare Pages. When you push changes to your repository, it automatically builds and deploys your site. This streamlines your workflow and eliminates manual steps.
Free and scalable hosting: Cloudflare Pages offers a generous free plan with no limits on the number of sites, requests, or bandwidth. So you can scale your project without worrying about sudden spikes in hosting costs.
Fast and reliable: Cloudflare's global CDN automatically distributes your content to servers worldwide, ensuring fast load times for all users, regardless of their location.
Free SSL certificates: Your site is always secure with Cloudflare Pages’s free, auto-renewing SSL certificates.
Collaboration features: Built-in preview deployments create temporary versions of your site for each pull request. This makes it easy for you and your team to review changes before they go live.

Ways to Deploy Astro Sites to Cloudflare Pages

You can deploy your Astro site to Cloudflare Pages in three main ways:

Cloudflare Pages dashboard: This is the simplest and most user-friendly method. It allows you to connect your Git repository directly to Cloudflare Pages through its web-based dashboard.
Cloudflare CLI (Wrangler): This approach uses Cloudflare's Wrangler command-line tool to deploy your Astro site. It allows you to preview your site locally for testing and debugging.
@astrojs/cloudflare (for an SSR site): If you've built an Astro site with Server-Side Rendering (SSR), you need to use the @astrojs/cloudflare adapter to deploy it to Cloudflare Pages. This adapter lets you use Cloudflare's Edge capabilities for better performance and scalability.

This tutorial will focus on the Cloudflare Pages dashboard method, as it's the most straightforward for beginners.

Prerequisites

Before we begin, make sure you have:

An Astro project ready for deployment
A GitHub or GitLab account (we'll use GitHub for version control)
A Cloudflare account (the free tier is sufficient)

Interactive Walkthrough Guide

You can learn how to deploy your Astro site through this interactive guide for a step-by-step experience. Alternatively, if you prefer to read at your own pace, continue scrolling to begin the tutorial.

Preparing Your Astro Project

Open your Astro project

Open your terminal and navigate to your Astro project's root directory. If you don't have one, follow these instructions in the official Astro documentation to create a new project.

For this tutorial, we'll use this simple Astro project as an example.

Set up a GitHub repository

Before deploying, you'll need to push your project to a GitHub repository. In your terminal, run these Git commands:

// Initialize a Git repository
git init

// Connect your GitHub repository
git remote add origin https://github.com/your-username/your-repo.git

// Stage all changes
git add .

// Commit your changes
git commit -m "Initial commit"

// Push to the remote repository
git push -u origin main.

Setting Up Your Cloudflare Account

Create a new Cloudflare Pages project

Sign up at Cloudflare.com if you don't have a Cloudflare account, then follow these steps to create a new Cloudflare Pages project:

Log in to the Cloudflare dashboard.
In the left sidebar on Account Home*,* click “Workers & Pages” and select “Overview.”
Click “Create” at the top of the page to create a new project. (If this is your first project, you’ll see the next step.)
In the "Create an application" modal, select the "Pages" tab.

Connect your Git repository

Click "Connect to Git" and sign in to your preferred Git provider. You'll be prompted to authorize Cloudflare's access to your repositories (all or select specific ones).

Select your Git repository

Choose the repository you want to deploy. Cloudflare Pages supports private and public repositories. Click "Begin setup" to proceed.

Deploying Your First Astro Site

Configure build and deployment settings

Set up your project details, including:

Project name: This will be used to generate your site's subdomain (e.g., your-project.pages.dev). It matches your Git project name by default.
Production branch: This is the branch Cloudflare Pages will use to deploy the production version of your site. (We'll use main for this tutorial.) You can change this later.

In "Build settings," set the following:

Framework: Astro
Build command: npm run build
Output directory: dist

Deploy your site

Click "Save and Deploy." Cloudflare Pages will build and deploy your Astro site. This process may take a few minutes.

View your deployed site

Once deployment is complete, you'll see a success message with a link to your newly deployed site. Click the link to view your live Astro site!

Updating Your Deployed Astro Site

Make changes locally

Update your content or code as needed. For example, we will add more content to index.astro.

Commit and push changes to GitHub

Once you're satisfied with your changes, stage, commit with a descriptive message, and push them to your main branch.

//stage your changes
git add .

//Commit with a descriptive message
git commit -m "Update content"

//Push to your main branch
git push origin main

Automatic deployment

Cloudflare Pages will automatically detect the new commit and start a new build. Once complete, your site will be updated with the latest changes. You can see all deployments in your project dashboard.

Known Issues and Limits with Cloudflare Pages

While Cloudflare Pages is a powerful platform for hosting Astro sites, it is important to be aware of some limitations:

Limited CI/CD integration: Currently, Cloudflare Pages supports automatic builds only with GitHub and GitLab.
Fixed repository selection: Once you choose a GitHub or GitLab repository for your Cloudflare Pages project, you can't change it. To use a different repository, you must delete your current project and create a new one.
Unchangeable subdomains: You can't modify your project's .pages.dev subdomain. To get a different one, delete your project and start fresh with a new one. However, you can still use custom domains for your production site.
Build limits: On the Free plan, Cloudflare Pages allows up to 500 builds per month. This limit applies to production builds, but you can have unlimited preview deployments. This is sufficient for most small to medium projects.

Conclusion

You've successfully deployed your first Astro site to Cloudflare Pages! Your site is now live and accessible, benefiting from Cloudflare's fast, reliable, and globally distributed hosting that complements Astro's performance-focused approach.

Throughout this tutorial, you've learned how to:

Prepare your Astro project for deployment.
Create a Cloudflare Pages project and connect it with your Git repository.
Configure Astro deployment and build settings.
Deploy your site and make updates.

Deploying your Astro site to Cloudflare Pages is just the beginning. The next step is setting up a custom domain for your site. Additionally, if you work with a team, you can implement preview deployments, creating temporary URLs for each pull request for easy review and testing changes before they go live.

Now it’s your turn! Share your deployed site or project you’re working on below.

Astro + Cloudflare Pages: A Beginner's Guide to Fast and Easy Deployment