Learnings on the Bleeding Edge

Following my mantra of staying on the bleeding edge with Astro, I had a couple of troubled days recently. Here’s what I learned from this experience.

Key Changes and Learnings

Astro introduced several features of Astro V5 as experimental features in the latest V4. Since I’m not using any JSX frameworks, the upgrade wasn’t too complicated. However, there were a few things that stood out in my setup, specifically with images in content collections. Here’s the Astro documentation on images in content collections.

Another critical feature that has now matured significantly is Astro’s content layer. You can read more about that in Astro’s deep dive into the content layer.

Changes I Made

Here are the specific changes I had to make during the upgrade:

1. Replace ViewTransition with ClientRouter in the head section:

+ import { ClientRouter } from 'astro:transitions';
- import { ViewTransitions } from 'astro:transitions';

+ <ClientRouter />
- <ViewTransitions />

2. Replace slug with id in content data:

Previously, I was using slug, but now I replaced it with id:

// Before
- const { data: post, slug } = blog;

// After
+ const { data: post, id } = blog;

3. Move Content Directories

I migrated my blog and other content directories from src/content to src/data:

src/
  └── data/
      └── blog/

4. Modify src/content/config.ts

I updated the content configuration to reflect the new directory structure, and I replaced the legacy API with the glob loader:

import { glob } from 'astro/loaders'; // No longer available with the legacy API

loader: glob({ pattern: "**/[^_]*.mdx", base: "./src/data/blog" });

5. Update package.json for Beta Modules

Finally, I updated my package.json to include the new beta versions of Astro and its plugins:

{
  "@astrojs/mdx": "4.0.0-beta.1",
  "astro": "5.0.0-beta.2"
}

Final Thoughts

While the upgrade process had its challenges, especially with being on the cutting edge, the maturity of Astro’s content layer and other improvements made it worthwhile. I look forward to more streamlined updates as Astro continues to evolve.