恒例のメジャーアップグレードが…
2024年12月にAstroがv5にメジャーアップグレードしたとのアナウンスがあった。v3からv4へアップグレードした際の問題は、せいぜいNode.jsのバージョンの不一致だったが、今回はいくつかの”breaking changes”があるらしい。
アップグレードに失敗したらどうしよう…と躊躇しているうちに2ヶ月が経過し、バージョンも5.3.1まで来た。メジャーアップグレードどは年に一度の恒例行事になりつつあるし、あまり先延ばしにもできないと重い腰を上げて取り掛かることにした。
まずは、公式のアップグレードガイドを読む。
「このコンテンツはまだ日本語訳がありません。」 だって（2025年3月2日現在）。ということで、頑張って英語版を読みましょう。
既にアップグレード済の先達が何人かおられるので、Googleさんに「Astro v5 アップグレード（アップデート）」と尋ねれば、いくつかの記事がヒットする。
アップグレードのコマンドを実行
いつもと同様、プロジェクトフォルダでコマンドを実行する
# npmの場合
npx @astrojs/upgradeいつものメッセージが出てくる。
Need to install the following packages:
@astrojs/[email protected]
Ok to proceed? (y)yで進む。
astro Integration upgrade in progress.
● @astrojs/partytown will be updated from v2.1.2 to v2.1.3
● @astrojs/rss will be updated from v4.0.8 to v4.0.11
▲ astro will be updated from v4.16.2 to v5.4.1
▲ @astrojs/tailwind will be updated from v5.1.2 to v6.0.0
wait Some packages have breaking changes. Continue?
● Yes ○ No 出たよ”breaking changes”。Astro本体だけでなく、インテグレーションのアップグレードもあるらしい。▲がメジャーアップグレードで●がマイナーアップグレードのようだ。
ここで怯まずにEnterキーで次に進む。
check Be sure to follow the CHANGELOGs.
astro https://docs.astro.build/en/guides/upgrade-to/v5/
@astrojs/tailwind
https://github.com/withastro/astro/blob/main/packages/integrations/tailwind/CHANGELOG.md#600
██████ Installing dependencies with npm...
+—————+ Houston:
| ^ u ^ Good luck out there.
+—————+ひとまずアップグレードできたようだ。
“Good luck out there.”だと…“breaking changes”に対応する我々の幸運を宇宙から祈っているのか？Astroなだけに。
落ち着いて事前にチェックしておいた修正を加えていくことにする。
v4からの変更点
アップグレードによる修正箇所は、プロジェクトで採用している技術やインテグレーションによって変わってくると思う。以下は、あくまで当サイトで行った修正である。
Legacy: v2.0 Content Collections API
Astro v5では、v2で登場したContent Collections APIがContent Layer APIに変更になった。
「Updating existing collections」 の「Step-by-step instructions to update a collection」に具体的な変更方法が説明されている。
1. config.tsの移動・リネーム
src/content配下にあったconfig.tsファイルをsrc直下に移動し、content.config.tsに
リネームする。
2. collectionの定義を編集
content.config.tsを修正する。
collectionの定義でtypeが使えなくなるので、loaderに変更する。
import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';
const blog = defineCollection({
type: 'content',
loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: "./src/data/blog" }),
schema: z.object({
title: z.string(),
...
}),
});3. 参照をslugからidに変更
Content Collection APIのidには.md拡張子込みのファイルデータ、slugにはスラッグのデータが格納されていたが、Content Layer APIになってslugのフィールド消えた。代わりに、idに以前のslugに相当するデータが格納されている。
そこで、src/pages/[slug].astroファイルなどで参照しているslugをidに変更する。
export async function getStaticPaths() {
const posts = await getCollection('post');
return posts.map((post) => ({
params: { slug: post.slug },
params: { slug: post.id },
props: post,
}));
}当サイトでは、記事のURLだけではなく前後の記事URLやsitemap.xmlやrss.xmlのURL出力でも使用していたので、そちらも忘れずに修正した。
4 render()関数への変更
getCollectionで取得できたrender()メソッドが使えなくなったので、render()関数をastro:contentからインポートして使う。
import { getCollection, render } from "astro:content"; // renderを追加
const { post } = Astro.props;
const { Content } = await post.render();
const { Content } = await render(post);その他の対応方法
Content Layer APIにすぐ対応できない場合は、astro.config.mjsでLegacy flagの設定をすると、引き続きContent Collection APIが使用できる。
しかし、今はレガシー扱いで使えてもいずれ非推奨になると思われるので、これは応急処置的な対応だろう。
Changed: TypeScript configuration
TypeScriptの構成がsrc/env.d.tsから.astro/types.d.tsに変更された。
src/env.d.tsを削除して、tsconfig.jsonに追記する。
{
"extends": "astro/tsconfigs/base",
"include": [".astro/types.d.ts", "**/*"],
"exclude": ["dist"]
}ローカルでサイトを確認
npm run devでローカルを立ち上げる。
astro v5.4.1 ready in 5256 ms
┃ Local http://localhost:4321/
┃ Network use --host to expose
14:32:11 watching for file changes...エラーが出ることなく、無事サイトが起ち上がった。事前に念入りに修正箇所を洗い出していたので、実作業は20分そこそこで済んだと思う。メジャーアップグレード怖い…と打ち震えていたのがバカみたいだ。
おわりに
ネットでは「難なく進められました」「アップグレードでハマった」と相反する反応が見られたので、スムーズに進められてよかった。
あまり難しい技術を採用していない当サイトでは必要なかったが、Viteが6.0にアップグレードしたことによるVite専用のインテグレーションの変更、@astro/mdxや<ViewTransitions />の仕様、Astro.glob()といった非推奨になった関数などなど、今回は”breaking changes”がもりだくさんなので、詳細は公式ガイドで確認することをおすすめする。
参考ページ
☕コーヒーをおごる
