Astroをv5からv7へアップグレード（with Claude Sonnet 5）

ほとんどブログ記事を更新していないうちに、今年も恒例のメジャーアップグレードが来た。しかも今年は2回来た。3月にv6になり、いずれアップグレードしようと呑気に考えているうちに、8月に気づいた時には再度のメジャーアップグレードでv7になっていた。

前回までは公式のドキュメント＋Google検索だったが、今回は公式ドキュメント＋Claude（Sonnet 5）の力を借りてアップグレードを行った。

アップグレードの進め方

v5（私の場合は5.15.4）からv7（7.2 ※8月末時点の最新版）へのアップグレードは、いきなりv7に上げるのではなく、v6の最新版（6.4）を経由する形で行う。

v6での主な変更点・1 - Node.jsのバージョン要件

v6ではNode.jsのバージョンが22.12.0以上が必須となり、しかも偶数バージョンのみサポートされる。

v6での主な変更点・2 - Content Collections周辺

v5で応急処置として使えていたContent Collections周辺の諸々が使えなくなる。

src/content/config.tsは読み込まれず、src/content.config.tsが必須に
legacy.collections フラグ廃止
スキーマの識別子が slugからidに統一。スキーマにslugフィールドがあるとContentSchemaContainsSlugErrorが出る

v7での主な変更点

Goベースのコンパイラが廃止され、Rustコンパイラへ完全移行したためHTML構文チェックが厳格化。閉じタグ漏れでビルドエラーになったり、不正なネストの自動修正が無くなりレイアウト崩れになるということもある。

その他の変更点は公式サイトを参照。

Upgrade to Astro v6

docs.astro.build

Upgrade to Astro v7

docs.astro.build

当サイトはv6での注意点をクリアしていたので、このままアップデートを進めた。

v6のバージョンを指定してインストール

pnpm dlx @astrojs/upgradeでアップグレードすると一気にv7になってしまうので、package.jsonで"astro": "^6.4.0"とバージョンを指定してからpnpm installでインストールする。

v6へアップグレード後のVS Codeのエラー

v6へアップグレードした後に、ある.astroファイルを開いたら、以下のようなエラーが出た。

モジュール 'astro' またはそれに対応する型宣言が見つかりません。
バインド要素 'paginate' には暗黙的に 'any' 型が含まれます。
インターフェイス 'JSX.IntrinsicElements' が存在しないため、暗黙的に JSX 要素の型は 'any' になります。

Claudeに訊いたところ、VS Codeのワークスペースで使用されているTypeScriptのバージョンが云々と返ってきたが、どうも要領を得ないのでVS Codeを一旦閉じて再起動したらエラーは消えた。

教訓：VS Codeでエラーが出たら、まずは再起動すること

v6で`build`する

アップグレードしたらpnpm astro buildを一度実行しておく。pnpm astro devでいいんじゃね？と思ったが、Claudeによると、

はい、build も実行しておくことを強くおすすめします。理由はいくつかあります。

devとbuildでは検証される範囲が違う

astro dev：オンデマンドでページを描画するだけで、型チェックは基本的に行いません（エディタの型エラーとは別物です）。また、実際にアクセスしたページしかレンダリングされないので、巡回していないページのエラーには気づけません

astro build：全ページ（動的ルートも含めて getStaticPaths で列挙されたすべてのパス）を実際にビルド時レンダリングするため、dev では踏んでいなかったコードパスのエラーが表面化しやすいです

なのだそうだ。devで大丈夫だと思って今までやっていなかった…。

`@astrojs/rss`のエラー

astro buildをしたら、rssを出力するためのファイルrss.xml.jsでエラーが出た。

[ERROR] TypeError: z.function(...).returns is not a function

Claudeによると「Zod v3→v4での破壊的変更が原因」で、Astro v6の要求するZod v4と噛み合っていないためという。これは、@astrojs/rssのバージョンを4.0.13から4.0.19にして再度ビルドしたら解決した。

v6からv7へアップグレード

v6でビルドできたのでV7にアップグレードした。pnpm astro devすると、以下のようなコンパイルエラーが出た。

[CompilerError] Unexpected token
  Stack trace:
    at C:/Users/PC_User/xxx/xxx/xxx/src/layouts/BaseLayout.astro:46:9
    [...] See full stack trace in the browser, or rerun with --verbose.

Google Tag ManagerのHTMLコメントが記述されている箇所だった。v7のRustコンパイラで厳格化されたことによるエラーだという。

解消するには、コメントを削除するか、もしくはJSX形式の{/* ... */}に変更する。

v4からv5へのアップグレードで大方対応済みだったので作業面の大変さはなかったが、予期せぬエラーが出たときは焦った。何はともあれ、今回も無事にアップグレードできて安心した。