Santanu
Santanu

Technology

Learnings on the Bleeding Edge

A reflection on my experience upgrading Astro and key lessons learned along the way

Astro 5 Beta
Astro 5 Beta

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:

BaseHead.astro
+ 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:

src/pages/blog/[slug].astro
// 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:

Terminal window
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:

src/content/config.ts
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:

package.json
{
"@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.

Read Next

12 Sept   2024

To my father

Written by Aarush for Santanu's 50th B-day

29 Sept   2024

The lost faith

Written by Aarush