Deploying Astro To Cloudflare Pages
I’ll kick this off with the following two statements:
- I love Cloudflare Pages
- Astro wasn’t my first choice
To address the first, I’m a big fan of Cloudflare, I really like their product design and Pages was no different. In fact it’s worth mentioning for full disclosure (without breaking NDA), I even participated in some of their product research for Pages. That’s one reason I like them, they know their audience because they get to know them. Another reason I like Cloudflare is their documentation quality, it’s great, extensive and aimed at developers - but here’s where our story takes a twist.
What Is Cloudflare Pages?
Let’s first look at the marketing page
Build fast sites. In record time.
Emphasis is from cloudflare.
Cloudflare Pages is a JAMstack platform for frontend developers to collaborate and deploy websites.
My summary would be that it’s:
- A hosting platform for static sites
- An opinionated CI/CD pipeline for popular frameworks
The emphasis from the marketing page is worth carrying over, it really is fast. Their network has a good part of that claim, but the nature of a static site is that it’s just grabbing static assets. It does integrate with workers as functions, allowing static sites to have some interactivity, the best of two worlds! 🙌
As previously mentioned, Cloudflare is great at docs and Pages is no different. It covers all the usual bits like how to set up via integrating GitHub/Gitlab apps and even goes into 31 (as of writing) frameworks setup, this is where we resume our story.
Picking A Framework
As I mentioned, cloudflare pages explicitly supports 31 different frameworks for deployment. Each one has a tutorial about how to setup the framework locally and then how to integrate and eventually deploy it. So I consulted the docs, having a few frameworks in mind that I was already considering, checking the support for each one.
I knew I wanted something relatively simple to work with. Markdown formatting, some additional plugins for things like embeds (like youtube videos) etc.
In Comes Zola
I initially landed with Zola, a rust based Static Site Generator (SSG). It didn’t entirely fit the criteria, but it did tick the simple and markdown boxes (and 🦀 hype train) so I decided to give it a go.
The installation process to develop locally was pretty damn simple. I didn’t write any content at that point I just wanted to ensure it deployed, and oh boy I’m glad I checked.
Zola is one of the frameworks that cloudflare supposedly supports, but I quickly found out that the docs for it had clearly been abandoned. The docs were aimed at cloudflare pages V1 not V2, but no where is this mentioned. Additionally I found that V1 no longer updates the binaries it caches, so I had to do a cumbersome bash script as an override environment variable 🫠 to even get a new version.
I eventually got it deploying, but what ended up deploying looked nothing like my local and I figured given I was using a deprecated version of the build pipeline with additional hacks on top of it to get a new binary version, it wasn’t worth the debugging effort.
Pages opinion on how to deploy changed, but its documentation didn’t. The fact that they include some dials to change in there (with env vars) is a concession from the start the solution wasn’t great. I think the product team fell short here both on the original developer experience and the transition to the new version by not updating docs.
My Old Friend Hugo
Hugo is a go based SSG and was a bit of a spiritual successor to Jekyll. It’s a single binary (like Zola) and really straight forward to use. They’re both quite similar in usage and design decisions, but Hugo has been around for longer and has a much larger ecosystem of plugins and themes. I’d say Hugo had a higher ranking in confidence from the start for me, but Zola was first choice for experimental reasons.
Unlike Zola, Hugo has actually been kept up to date and is buildable in V2 pipelines for pages.
So I quickly nuked my Zola setup and generated a new boilerplate site into the same folder, committed and 💩 the site doesn’t build. It requries a theme. A little sad that they don’t have some kind of fallback built in theme but fair enough, I’ll grab one from the gallery of many OSS themes out there.
I installed a theme via the usual git clone command, straight into the themes folder, committed and 💩 Aghh! Foiled again! It turns out Pages wasn’t pulling the theme contents because it technically never committed. You have to specify the folder as a gitmodule. It also has to be a https URI or Pages can’t clone it. A little bit of a gotcha there.
I had a little bit of trouble too actually getting the git module up and running. I’ve been a git cli advocate my entire career, but I recently switched to GitButler (a GUI for git with some nice features) and it doesn’t support git modules (as of the writing of this). I did try to quickly create my own theme but realised installing things like tailwind and integrating that into the V2 opinionated pipeline just wasn’t worth the effort, I just wanted to write and customize as I went in the future, not all in from day one.
Going Retrograde With Astro
Astro really wasn’t on my list of frameworks to even try out for a blog. It just so happened while searching for an easy way to add a framework like tailwind into Hugo that I spotted a comparisson between Hugo and Astro. I have used Astro before and know it can be used as an SSG (in fact thats its primary mode), but I hadn’t really considered it for a blog.
Astro is a little hard to conceptualise when you’re coming in from the angle of creating websites from markdown. It’s closer to website frameworks than it is an SSG, and yet its primary focus is SSG. Markdown is a first class citizen, so that box is ticked. It’s javascript and has an integration/plugin system so that box is ticked. It even had a built in blog template that wasn’t painful to configure and was selectable via the CLI generator, so I think it has ease covered too.
Astro is one of the supported frameworks for Pages. In fact Astro the framework explicitly targets cloudflare with one of its adapters. It means you can even add interactivty into the site via workers. It has some built in options to integrate with other cloudflare services such as the image optimiser.
I was up and running in about 20 minutes, it was seriously easy. Customisation of the default blog theme was a breeze because it’s treated more like a site than it is a theme, so you just go in and edit the .astro files which are pretty similar to a .tsx/.jsx experience.
Astro has support in the Pages caching mechanism too, so given the high quality adapter that has been written and the caching, it seems like the devs work closely with the Pages team.
Conclusion
As of writing this entry, the site is deployed on Pages using Astro. I’m enjoying my experience with it so far and look forward to writing some more entries with my experience in the tech industry.
Cloudflare - Please update your docs, you don’t have to have the opinion that every framework should be supported and documented, clearly you’ve not been able to keep up with this. Instead, follow the framework you’ve built with the Astro team, where it’s a symbiotic relationship, be opinionated on core tenets of making the framework installation quick and easy in the pipeline and frameworks have to work around you (such has having an adapter/detecting the build environment).