Blog Logo

Creating a simple site with Astro and publish it to Cloudflare Pages

Table Of Contents

If you look at the second post in this site, you’ll notice that I used to use GatsbyJS for publishing this blog, and that worked fine for a while. But some issues started to arise:

So after 4 years, it was time to switch technologies and republish my blog, but there was one big caveat, it should be a static blog generator with support to Markdown.

The first thing I tested out was site builders like Jekyll and Hugo, which are great, but they still need intermediate steps when I want to publish my information to a basic Web Server.

Luckily, while looking into publishing tools, I ran into Astro and I fell in love with how straight forward it is and specially how fast the build step runs.

Here are some notes on the things I learned while reading upon Astro

But What is Astro

I’m just going to say here that Astro is an all-in-one web framework for building fast, content-focused websites. (taken from the official site)

If you really want to learn Astro, you should really look into it’s documentation. Is very clear and basic, but also very thorough…, and kind of long.

That’s it.

Astro Setup

Setup could not be easier just an npm create command and your off to the races.

npm create astro@latest learn-astro-cloudflare-portfolio
cd learn-astro-cloudflare-portfolio
echo "# Astro Portfolio site published in Cloudflare" > README.md
npm install
git init
git branch -M main
git add .
git commit -m "Project init"

The first cool thing you’ll encounter is the guided setup that Astro offers:

Terminal app running Astro's npm create command

Things to note regarding setting up a new project.

After you finish the setup, this is the file structure you’ll end up with:

$ tree -I node_modules
.
├── README.md
├── astro.config.mjs
├── package-lock.json
├── package.json
├── public
│   └── favicon.svg
├── src
│   ├── env.d.ts
│   └── pages
│       └── index.astro
└── tsconfig.json

4 directories, 8 files

If you are in a hurry, you can create the site using a template and pass all answers:

npm create astro@latest my-new-blog -- --template blog --no-install --no-git --typescript strict

The -- is to pass options to astro and not to npm

Starting Development

After you install Astro, you can just execute the dev command to get a Live Reload development environment

npm run dev
Terminal app running Astro's npm run dev

And then, you can visit http://localhost:4321 to see a live preview of your site:

Astro project running in localhost on port 4321

You can also build your site (convert it to plain html and CSS) by executing the build command:

npm run build

And look at the results in the dist/ folder.

Publish to CloudFlare

By default, Astro is a site builder. This means that when you “build” your project you’ll get a bunch of HTML and CSS that can be pushed to regular Http server. And that’s what CloudFlare Pages offers (well in reality a little more but that’s what we need right now), a place where you can publish a basic website right from GitHub.

One cool thing about CloudFlare Pages is that is going to take care of pulling your Astro code from GitHub, convert it (build) to HTML and then publish it. With Astro, the time between pushing your site to the cloud and actually being able to see it live is measured in seconds instead of minutes like other solutions.

Our first victory then, would be publishing this repo to CloudFlare pages and see it go live in like 10 seconds.

But first, we need a GitHub repository to push the code to the cloud.

Create a GitHub Repo

The first step would be to create a repo on GitHub and sync our local files with it

GitHub's new project page
git remote add origin [email protected]:marioy47/learn-astro-cloudflare-blog.git
git branch --set-upstream-to=origin/main main

Create a CloudFlare “pages” Project and Connect it to GitHub

The second step is to create a new Pages project in CloudFlare and connected to the repo we just created:

CloudFlare's dashboard showing pages & workers overview CloudFlare's dashboard showing connect to GitHub button

CloudFlare pages will redirect you to GitHub for authentication. In GitHub select to give access just to the repo we just created and then select the repo from the drop down (in our case I just started typing astro to get the repo).

GitHub's dashboard authorizing repo to be installed

The GitHub will redirect you back to CloudFlare where you have to select the repo you just created, which branch will be deployed (in our case main) and the build command.

CloudFlare's dashboard showing linked repo

Fortunately, CloudFlare is aware of Astro so instead of typing the build command, you only have to select from the drop-down Astro, and the build command will be entered for you.

CloudFlare's Astro configuration options

And when you click Save and Deploy CloudFlare will pull a copy of the repo and execute the build command while showing you the progress.

CloudFlare's dashboard showing first build results

Also notice that it has created a new domain for your app. In this case is https://learn-astro-cloudflare-portfolio.pages.dev

CloudFlare's dashboard showing created domain

After the first deployment you’ll get a unique URL of your project which you can open in a browser and see the results

Website after first deployment

CloudFlare Custom Domain and Caching

If you are also using CloudFlare to manage your domain records, which you should, you can go into the DNS settings and change the provisional domain for something more user friendly. The steps are simple:

Also, and highly recommended, is that you enable Build Caching so the time between pushing changes to the cloud and the final publishing goes from 10-15 seconds to 1-2 seconds:

Testing a Change in a Page

Now that you have your site in CloudFlare Pages and you have your deploy process from GitHub to CloudFlare in place, pushing a change is ridiculously easy:

sed -i "" "s/>Astro/>Mario's Blog/g" src/pages/index.astro # The change
git add src
git commit -m 'doc: testing a change in the homepage'
git push

Two things to note:

CloudFlare's dashboard showing second deployment Website after second deployment

As you can see CloudFlare + Astro is a match made in heaven.