From Next to Astro

This is not the first time I’ve re-platformed this blog. It was originally a Gatsby based site, which I wrote about upgrading (painfully) here: The Great Gatsby - Upgrade. It was very briefly a Statamic site which I wrote about here: Statamic on Digital Ocean App Platform. After that it went to Next JS which I guess I never wrote about, but trust me on that one.

Recently I switched the Shelf Love Podcast site from using the Next app directory instead of the pages directory, a new and fairly major change to Next’s architecture. It was an overall improvement from the ISR strategy that site was using before.

After moving over Shelf Love I thought “well why not my site too”. I did migrate it to using the app directory, and it’s been running that for a while now, but I find Next’s app directory structure for a blog built off of simple markdown files to be unnecessarily complex.

What should a web framework do for me?

In general:

  • It should be obvious where the HTML, CSS, and JavaScript are coming from and how they will be delivered.
  • It should be easy to add data to those views and reduce duplication of code.
  • If there’s a common pattern or new web API with compatibility issues, it should offer an API or wrapper to make it easy to implement.

My issue is Next has made changes over time that make those three points feel more complicated than they need to be. For example:

  • Next/Image and Next/Link had major changes between version 12 and 13, and they still come with more caveats and undocumented sharp points than I think a replacement for the <a> and <img> tags should. next/font falls into this bucket too. It’s a similar pattern to what I hated in Gatsby, where a common need (load a font) gets wrapped into a plugin that’s more complex than implementing it without the plugin.
  • I’ve seen a dozen different ways to hoist metadata to a page layout, but I find Next’s generateMetadata to be an incredibly unintuitive solution with too much magic happening. If I wrap a page in a parent Layout, let me pass the metadata to it — exactly how it worked with the pages directory.
  • Similarly, Next’s options for dealing with cached content. I get that they’re covering a lot of scenarios here, but it’s much more “you can handle any case” over “here’s a great and easy way to handle 98% of cases”.
  • There’s many other things in Next land that are only relevant to Next land. For example, this Third Party Libraries page. Again, this feels like too much of a split from “how the web just works” with little benefit to the developer or user.

I know there’s been a fair amount of pushback on the web at large about Next and React merging into one thing wherein all the secrets of the bestest and fastest ways to build an entire website out of React live. I don’t share those particular feelings — I think any given library/language will have it’s favorite framework to build on, and they’ll push/pull each other forward. My desire to change to something else for the purposes of blogging is simply…

I don’t want to think about it

Which is to say, if I put content in a folder, I expect it to become a page on the site, and if I want to load JavaScript that isn’t React (gasp, shock), it shouldn’t be hard. And if I want to look at what the page is sending over the wire it should be mostly HTML.

So now this site is built with Astro. The conversion was fairly straightforward given that the Astro template files use JSX, and for the parts of this website that can’t just be static HTML (like the Mastodon comments section I just made, Astro makes it easy to import a React component and render it on the client.

And while I was using Tina CMS to update and modify content, I haven’t implemented that with Astro yet. Astro’s markdown querying and rendering does enough for me, and I wasn’t blown away by Tina’s content organization so I’m skipping it until I find a reason to need it.


Go check out Astro, I think it’s a pretty good solution for a BYOB (build your own blog). In fact one of their starters is a blog template, and I liked a few bits of the layout so much I stole them for this site.

And thanks to Mike Susz for indirectly convincing me not to use Astro when it probably would have just annoyed me, and suggesting to use it when it was a good fit 🙂.

"loading posts from Mastodon..."