Migrating from Gatsby to Astro

An update

So it’s been a while since I’ve updated my blog. Although I’ve kept going with a few side learning projects over the years I never got around to updating my blog as life happens I guess. I’ve even been doing some freelance work recently (almost a couple of years) which can really use up what little time I have outside work, family, house stuff and other things. I am keen to do a bit more blogging though so let’s see how that goes!

Why Astro?

Why the move from Gatsby to Astro? Well, it’s really driven by the fact we’ve been looking into Astro at work and I needed to do some research in my own time. There’s no issue with Gatsby itself and my personal blog / site has been fine all this time since I migrated to it around 4 years ago. The other part is that my site has been unloved and unmaintained for a few years so it’s an opportunity to keep using my site as a test bed for a bunch of other more recent technologies.

The process

First up I’ve been following the Astro guides and documentation for getting a boilerplate local instance up and running. Pretty straightforward as the npm create astro@latest wizard helps step through a few options like folder name, which package manager, use TypeScript, starter template, etc. I went with a blog template which does a fair bit of setup although you can start from a community template also.

Page migration

For static blog pages this is pretty easy. Copy them into the relevant section of the content folder as that has .md / .mdx support and allows the newer “Collection” approach (more on that later). If you’re running the local environment with npm run dev then hopefully you’ll have your pages up and running. In my case there was a bit of stuff to update due to Front matter as explained in the section below.

Front matter

So it’s most likely your frontmatter format will be different, even if it’s only slightly. That’s not really a big deal unless you’re needing to update a lot of pages manually. The alternative is to just edit the content config file of your Astro template (it’s just using Zod to validate a schema so easy enough to change here and the blog template).


Your Gatsby site probably has a different folder structure for source code and static assets. In this case maybe a bulk copy of images from the old site and a find and replace on file paths is the most basic way forward.

Additionally the starter theme / template I began using in Astro had hero images for the blog posts. I could have removed these but decided to go with it as it allowed me to add some colour and visual appeal. I went off and grabbed some freely available images, cropped and resized them to suit.


Has your site route structure changed in the migration? Mine did as my blog posts moved from a root level /* into a /blog/* sub-level. 301 redirects time!

Astro supports redirects which follow the same rules as file-based routing. In my case I had a limited set of redirects so I just did them manually in the config file as in the instructions. I also had to update the slug to the correct path as the fallback of filenames wasn’t quite right (I was using path in Gatsby).

export default defineConfig({
  redirects: {
    '/old-page': '/new-page'

Blog posts listing

My previous Gatsby theme already had a loop for all the blog posts on the homepage but I needed to recreate this for my Astro homepage. Given I set up the blog as a content collection I was able to use the getCollection method within the frontmatter section as below.

const allBlogPosts = await await getCollection("blog");

I was able to sort the posts by publication date so the newest were at the top.

const orderedPosts = allBlogPosts.sort(
  (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf(),

IDE Integration

There’s not a lot different here however .astro files aren’t detected automatically (at least with VS Code) without adding the appropriate extension. I had issues getting prettier to work but I did go the manual config route as described in the plugin but if you’re just using the Astro VS Code extension you should be fine.


So we explored the process of migrating from Gatsby to Astro and covered various aspects that you’re likely to encounter during the switch. Was it worth it? I’m not sure yet although I feel like it was fairly straight forward compared to when I first set up Gatsby although I don’t think the ecosystem is quite as powerful yet from what I’ve seen. Either of these frameworks are very confident but at least I’m getting some exposure to the Astro way to doing things.

I still have a bit I want to finish setting up such as grouping by tags and adding a few things like reading time. If there’s enough to cover in another post I’ll do that soon.

Happy coding!