Deploy Astro to Cloudflare Pages: A Step-by-Step Guide

Astro has been gaining traction for its performance and flexibility. Today, I'm going to guide you through deploying an Astro project to Cloudflare Pages with the help of the Cloudflare adapter. We'll go through the process of setting up a new Astro project, adding a server-side rendered page, pushing your project to GitHub, and finally, deploying it to Cloudflare Pages.

First things first, make sure you have an Astro project ready for deployment.

Setting up a New Astro Project

If you're new to Astro, you can create a project with the following command:

npm create astro@latest

This will guide you through some initial setup questions. For more details, check the Astro documentation.

Once your project is ready, you can run it locally:

npm run dev

Your Astro project should be live at http://localhost:4321. If you see the Astro welcome page, you're good to go.

Adding a Server-Side Rendered (SSR) Page

Astro supports static and server-side rendered pages. By default, a new Astro project starts with a static page. Let's add an SSR page to see how the Cloudflare adapter manages both page types.

Create a file named time.astro in the src/pages directory with this content:

// src/pages/time.astro
---
const date = new Date();
const formattedDate = date.toDateString() + ' ' + date.toTimeString();
---

<html>
  <body>
    <h1>Hello World</h1>
    <p>Current date: {formattedDate}</p>
  </body>
</html>

This page will show the server's current time, updating with each page refresh.

Run your project locally again, and you should find the new page at http://localhost:4321/time. If you refresh the page, you should see the time update.

Pushing Your Project to GitHub

Now that we have an Astro project, we need to push it to GitHub so that we can deploy it to Cloudflare Pages. The process is simple, and I'm sure you've done it a million times, but just in case, here are the steps:

Create a new repository on GitHub.

I'm going to call mine astro-cloudflare-example. You can call yours whatever you want.

Initialize a new Git repository in your Astro project.

git init

Add your files to the Git repository.

git add .

Commit your files.

git commit -m "First commit"

Add your GitHub repository as a remote.

git remote add origin git@github.com:<username>/astro-cloudflare-example.git

Push your files to GitHub.

git push -u origin main

P.S. Don't forget to make your repository private if you don't want the world to see your code. (You don't want the world to see your code, do you?)

Getting Started with the Cloudflare Adapter for Astro

Before deploying your Astro project, you need to install the @astrojs/cloudflare adapter. This is easily done via the Astro CLI:

# Using NPM
npx astro add cloudflare
# Using Yarn
yarn astro add cloudflare
# Using PNPM
pnpm astro add cloudflare

This command will not only install the adapter but also apply the necessary changes to your astro.config.mjs file. Alternatively, you can install the adapter manually by running:

npm install @astrojs/cloudflare

Once the adapter is installed, you'll need to add it to your astro.config.mjs file. Open the file and add the following code:

// astro.config.mjs
import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";

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

The adapter is now installed and configured. Let's push our changes to GitHub and head to Cloudflare Pages to deploy our project.

Setting up Cloudflare Pages and Deploying Your Astro Project

Head to Cloudflare Pages, log in, and click the "Create a project" button.

Switch to the Pages tab, select your GitHub repository, and click the "Begin setup" button.

On the next screen, you'll be asked to select your build preset and build command. Select "Astro" as your build preset and enter npm run build as your build command and /dist as your output directory.

Click the "Save and Deploy" button, and on the next screen, you should see your project building. Once the build is complete, you'll be able to view your project at the URL provided.

2023-12-29T18:48:45.038755Z  Cloning repository...
2023-12-29T18:48:46.049357Z  From https://github.com/<username>/astro-cloudflare-example.git
2023-12-29T18:48:46.050014Z   * branch            ec16c14380f0662cd8acb55e9d43b0f80b5f0bde -> FETCH_HEAD
2023-12-29T18:48:46.050254Z
2023-12-29T18:48:46.098366Z  HEAD is now at ec16c14 WIP
2023-12-29T18:48:46.098967Z
2023-12-29T18:48:46.206323Z
2023-12-29T18:48:46.23878Z   Success: Finished cloning repository files
2023-12-29T18:48:47.18565Z   Detected the following tools from environment: npm@9.6.7, nodejs@18.17.1
2023-12-29T18:48:47.18656Z   Installing project dependencies: npm clean-install --progress=false
2023-12-29T18:48:55.842736Z
2023-12-29T18:48:55.843234Z  added 504 packages, and audited 505 packages in 8s
2023-12-29T18:48:55.843424Z
2023-12-29T18:48:55.843575Z  187 packages are looking for funding
2023-12-29T18:48:55.843724Z    run `npm fund` for details
2023-12-29T18:48:55.844947Z
2023-12-29T18:48:55.845295Z  found 0 vulnerabilities
2023-12-29T18:48:55.863123Z  Executing user command: npm run build
2023-12-29T18:48:56.711657Z
2023-12-29T18:48:56.711963Z  > major-motion@0.0.1 build
2023-12-29T18:48:56.712139Z  > astro check && astro build
...
2023-12-29T18:49:05.038488Z  18:49:05 [build] Server built in 1.32s
2023-12-29T18:49:05.038867Z  18:49:05 [build] Complete!
2023-12-29T18:49:05.073637Z  Finished
2023-12-29T18:49:05.074239Z  Found _worker.js in output directory. Uploading.
2023-12-29T18:49:06.379712Z  ✨ Compiled Worker successfully
2023-12-29T18:49:06.45732Z   Found _routes.json in output directory. Uploading.
2023-12-29T18:49:06.47374Z   Validating asset output directory
2023-12-29T18:49:07.212889Z  Deploying your site to Cloudflare's global network
2023-12-29T18:49:10.398114Z  Uploading... (1/1)
2023-12-29T18:49:10.399087Z  ✨ Success! Uploaded 0 files (1 already uploaded) (0.21 sec)
2023-12-29T18:49:10.399308Z
2023-12-29T18:49:10.657354Z  ✨ Upload complete!
2023-12-29T18:49:12.988071Z  Success: Assets published!
2023-12-29T18:49:15.532269Z  Success: Your site was deployed!

Testing Your Astro Project on Cloudflare Pages

Once your project has been deployed, you can view it at the URL provided. If everything went well, you should see the Astro welcome page. If you now navigate to the /time page, you should see the current time displayed. If you refresh the page, you should see the time update.

This page is server-side rendered and runs on Cloudflare Workers. This is particularly useful for pages that require dynamic content such as a product page or user profile page. I've written a detailed article on ISR with Astro if you're interested in learning more.

At this point, we have a working Astro project deployed to Cloudflare Pages. In addition, we have a Continuous Deployment (CD) pipeline set up. This means that every time we push changes to our GitHub repository, Cloudflare Pages will automatically build and deploy our project. I suggest you make a small change to your project and push it to GitHub to test this out.

Conclusion

That's pretty much it! You now have a working Astro project deployed to Cloudflare Pages. There are, of course, many more things that you can do with Astro and Cloudflare Pages. For example, we can add a custom domain to our project, so we don't have to use the Cloudflare Pages URL. We can also add a custom 404 page and set up redirects. I'll cover these topics in future articles.

Until then, happy coding!

Interested in LogSnag?

Get started right now for free!