How I migrated my blog from Gatsby to Astro

I’ve been running this blog on Gatsby since 2020. It served me well, but lately I found myself dreading every time I needed to make changes. The build times were slow, the dependency tree was massive, and honestly, Gatsby felt like it was designed for a different era of web development.

So I decided to migrate to Astro. And I’m glad I did.

Why I Left Gatsby

Don’t get me wrong, Gatsby was revolutionary when it came out. The idea of using React to build static sites with GraphQL as a data layer was genuinely innovative. But over time, the complexity started to outweigh the benefits:

1. Heavy dependency tree - My node_modules folder was massive. Every update felt like a gamble.
2. GraphQL for everything - Even simple things like reading a markdown file required GraphQL queries.
3. Slow builds - What should have been instant felt sluggish.
4. Plugin ecosystem chaos - Plugins would break with updates, and finding compatible versions was frustrating.

Why Astro?

Astro takes a fundamentally different approach. Instead of shipping a JavaScript framework to the browser by default, it ships zero JavaScript. You only add interactivity where you need it.

Here’s what sold me:

• Zero JS by default - Your pages are pure HTML until you explicitly add client-side JavaScript
• Content Collections - Type-safe markdown/MDX with built-in validation
• Simple file-based routing - No GraphQL, no complex configuration
• Framework agnostic - Use React, Vue, Svelte, or nothing at all
• Fast builds - My entire site builds in under a second

The Migration Process

Here’s the step-by-step process I followed. If you’re running a similar Gatsby blog, this should help you migrate smoothly.

Step 1: Create a Backup

Before touching anything, create a backup branch:

1
git checkout -b gatsby-backup
2
git checkout -b astro-migration

This way you can always go back if something goes wrong.

Step 2: Clean House

Remove all Gatsby-specific files. This includes:

• gatsby-*.js files (config, node, browser, ssr)
• The gatsby/ directory with page creation logic
• React components in src/components/
• Templates in src/templates/
• GraphQL hooks in src/hooks/
• SCSS/CSS modules
• Jest tests and Flow types
• Docker and CI/CD files you won’t need

Keep these:

• Your markdown content (content/posts/, content/pages/)
• Static assets (static/ - will become public/)
• Your site configuration (you’ll convert this)

Step 3: Initialize Astro

Create a new package.json and install Astro:

1
{
2
  "name": "your-blog",
3
  "type": "module",
4
  "scripts": {
5
    "dev": "astro dev",
6
    "build": "astro build",
7
    "preview": "astro preview"
8
  },
9
  "dependencies": {
10
    "astro": "^5.0.0",
11
    "@astrojs/sitemap": "^3.0.0",
12
    "@astrojs/rss": "^4.0.0"
13
  }
14
}

Create astro.config.mjs:

1
import { defineConfig } from 'astro/config';
2
import sitemap from '@astrojs/sitemap';
3

4
export default defineConfig({
5
  site: 'https://your-domain.com',
6
  integrations: [sitemap()],
7
});

Step 4: Set Up Content Collections

This is Astro’s killer feature. Create src/content/config.ts:

1
import { defineCollection, z } from 'astro:content';
2

3
const posts = defineCollection({
4
  type: 'content',
5
  schema: z.object({
6
    title: z.string(),
7
    description: z.string(),
8
    pubDate: z.coerce.date(),
9
    category: z.string(),
10
    tags: z.array(z.string()).default([]),
11
    draft: z.boolean().default(false),
12
  }),
13
});
14

15
export const collections = { posts };

Now move your markdown files to src/content/posts/.

Step 5: Update Your Frontmatter

Gatsby and Astro use slightly different frontmatter conventions. Here’s the mapping:

So this Gatsby frontmatter:

1
---
2
template: post
3
title: My Post
4
date: 2024-01-15T00:00:00.000Z
5
---

Becomes:

1
---
2
title: My Post
3
pubDate: 2024-01-15T00:00:00.000Z
4
---

Step 6: Create Your Layouts

Astro uses .astro files which combine HTML, CSS, and JavaScript in a single file. Create src/layouts/BaseLayout.astro:

1
---
2
import '../styles/global.css';
3

4
const { title, description } = Astro.props;
5
---
6

7
<!doctype html>
8
<html lang="en">
9
  <head>
10
    <meta charset="UTF-8" />
11
    <title>{title}</title>
12
    <meta name="description" content={description} />
13
  </head>
14
  <body>
15
    <slot />
16
  </body>
17
</html>

The <slot /> is where your page content goes - similar to {children} in React.

Step 7: Create Your Pages

Astro uses file-based routing. Create src/pages/index.astro:

1
---
2
import BaseLayout from '../layouts/BaseLayout.astro';
3
import { getCollection } from 'astro:content';
4

5
const posts = await getCollection('posts', ({ data }) => !data.draft);
6
const sortedPosts = posts.sort(
7
  (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf()
8
);
9
---
10

11
<BaseLayout title="My Blog">
12
  <h1>Latest Posts</h1>
13
  {sortedPosts.map((post) => (
14
    <article>
15
      <h2><a href={`/posts/${post.slug}`}>{post.data.title}</a></h2>
16
      <p>{post.data.description}</p>
17
    </article>
18
  ))}
19
</BaseLayout>

For dynamic routes like individual posts, create src/pages/posts/[...slug].astro:

1
---
2
import { getCollection } from 'astro:content';
3

4
export async function getStaticPaths() {
5
  const posts = await getCollection('posts');
6
  return posts.map((post) => ({
7
    params: { slug: post.slug },
8
    props: { post },
9
  }));
10
}
11

12
const { post } = Astro.props;
13
const { Content } = await post.render();
14
---
15

16
<article>
17
  <h1>{post.data.title}</h1>
18
  <Content />
19
</article>

Step 8: Update Netlify Configuration

If you’re on Netlify like me, update netlify.toml:

1
[build]
2
  command = "npm run build"
3
  publish = "dist"
4

5
[build.environment]
6
  NODE_VERSION = "20"

That’s it. Netlify will automatically detect Astro and deploy your site.

The Results

The migration took me about a day. Here’s what changed:

The JavaScript difference is the killer stat here. Gatsby ships React to every page by default. Astro ships nothing unless you explicitly add client-side interactivity with client: directives.

Things I Learned

1. Start fresh, don’t port - Don’t try to convert your React components to Astro one-by-one. Start with a blank slate and build what you need.

2. Content Collections are amazing - The type-safe markdown with Zod validation catches errors at build time instead of runtime.

3. You probably don’t need React - For a blog, Astro components are more than enough. I only have a small script for dark mode toggle.

4. Keep your URLs - Make sure your post slugs match the old ones so you don’t break existing links.

5. Test locally first - Run npm run build && npm run preview before deploying.

Should You Migrate?

If you have a content-focused site (blog, docs, portfolio) and you’re frustrated with your current setup, yes. Astro is genuinely simpler and faster.

If you have a highly interactive application with lots of client-side state, Astro might not be the right fit. Stick with Next.js or Remix.

For me, it was the right call. The site is faster, the codebase is simpler, and I actually enjoy making updates now.

The best framework is the one that gets out of your way and lets you focus on content. For me, that’s Astro.