Jul 7, 2025

Moving from Gatsby to Astro

You may have noticed I don’t blog much.

To be honest, a fair chunk of that is wanting to genuinely stay the fuck offline and hang around with real human beings rather than spend precious hours in the ever-fleeting days obsessing over people who seem to live entirely in my phone.

Another reason I’ve been avoiding blogging is Gatsby.

Back in 2019, I made the choice to start my own blog, but instead of using something off the shelf like Blogger or Wordpress, I decided that I pretty much wanted to own my entire blog - from the code to the actual blog bits that appear on the website - no advertising bullshit or creepy trackers, and no corporate overlord pulling the strings on me. And besides, I was a developer at the time, so it can’t be too difficult to start a blog, right?

One of the biggest temptations was a framework called Gatsby. If you’ve ever done frontend development in 2019 or so, and your website involved static sites, Gatsby was the big dog at the time. It was built on top of React (which at the time, that was one of the biggest frontend frameworks out there) so for me it seemed easy to get my head around and develop.

At the time, my head was in the frontend space so Gatsby seemed and felt intuitive. It’s just React/JSX bits of code to make the blog page, to make the blog slugs, to setup SEO, all that good stuff. And honestly? At the time, it worked beautifully

The problem with a lot of these frontend frameworks (and something that does kind of worry me about Astro, but I am jumping the gun here) is that they are absolutely brilliant to get up and running, but the technical debt just snowballs like crazy. It’s not really the framework’s fault - it’s more of the rapidly iterating culture in the frontend space that makes things seem rapidly obsolete.

Back then, I subscribed to the philosophy of “if it ain’t broke, don’t fix it”, and in terms of my little Gatsby blog it meant that I would stay on the exact Gatsby version unless there was some real reason to go through the pain of upgrading. It’s still a philosophy I live by, but I think with frontend libraries I would consider minor version upgrades (providing the frameworks don’t put a breaking change in the minor version - you’d be surprised how often that happens in the frontend NPM world…)

This came to a head when I bought myself a new Mac Mini with the new M1 chip back in 2020. That Mac Mini was an absolute beast in terms of performance! The problem on the other hand was that I couldn’t build my Gatsby blog on the M1 due to one of Gatsby’s dependencies not being built for the new M1 processor (it was still stuck with the Intel chips).

Eventually, this was fixed in Gatsby, and this meant that I would need to update my Gatsby version. Admittedly I think this went smoother than I initially thought it would as it was a bit of a straightforward upgrade. However, at this point I had many painful experiences of having to do an upgrade and having to deal with missing dependencies or dependencies that the authors had long abandoned (it’s very common in frontend development). I was honestly dreading the prospect of upgrading Gatsby or even remotely tinkering with Gatsby under the hood.

This year I had to replace the Helmet library that was provided by Gatsby/React and pretty much just did the SEO stuff in raw HTML in my Gatsby project. While that was nice, it did leave me thinking what was the point of having APIs to deal with the header/SEO components if it was just going to end up deprecated down the line?

I guess this is really the problem I have with Gatsby, with React, and with frontend development in general is a lack of forward planning of the APIs that are made for other developers. There is so much churn in the frontend space that nothing ever feels solidified, that the goalpost is always moving.

Even in an extremely mature framework like React, there is still this churn. The example I can give is Helmet - an API designed to abstract away the <head> aspect of HTML/website design - only for it to be deprecated to the point where I had to write the SEO manually in HTML in the end!

Astro is a bit different. You have what feels like two files joined up into one. Let me give you an example - here is my Footer.astro file:

---
const today = new Date();
---

<footer>
	&copy; {today.getFullYear()} rootfs.ext2.gz. All rights reserved.
</footer>
<style>
	footer {
		padding: 2em 1em 6em 1em;
		background: linear-gradient(var(--gray-gradient)) no-repeat;
		color: rgb(var(--gray));
		text-align: center;
	}
</style>

The first bit is the necessary JS info that needs to be referenced in the HTML. The JS is simply referenced with {} like in React.

The beauty here is a few things:

For the most part, I’m writing bog-standard HTML. None of the HTML is abstracted away from me. This means that if I learn some new HTML element, I don’t need to look up the special Astro version of that call, or wait until Astro supports the element down the line.
The JS at the beginning is effectively ran when Astro builds the entire project, and it sticks the result of {today.getFullYear()} in the HTML itself, so you don’t get needless JS existing on the page just for the sake of providing the year.
If I wanted to add some interactivity to the page, I can just slap a <script> in the page, and Astro will do its magic and turn that into a JS/TS bundle (yes, it supports Typescript too) - you can read about it more on their docs.

Now, with all that hype out of the way, Astro isn’t perfect. I was looking into Content Security Policy (because why not) and it’s… uh… it’s experimental. Worst of all, it seems due to the way Astro builds all the JS that the CSP stuff is quite hairy to add manually, so you absolutely need that abstraction layer that Astro provides.

On the one hand, I can see the justification for abstracting this into an Astro API, but after years of React and the whole frontend experience, I’m not exactly keen on the abstraction layer (not looking forward to having to rip that API out or change the params because the developer who wrote the API didn’t care to foresee potential changes).

Admittedly though, this is such a tiny silly example. On the whole I am tremendously happy I have migrated over to Astro - it just feels common sense in all the best ways. It’s out of the box just barebones HTML and JS (and if you really miss React, you can add it, but good grief why would you?).

Ah, and that’s another reason why I don’t blog much - this article alone took me an hour and a half to write.