Astroをv2からv4にアップグレードした時の作業覚書

個人のポートフォリオサイトをAstroでv2からv4にアップグレードする際の手順やエラーについてのメモが含まれています。アップグレードにはCLIコマンドを使用し、バージョンアップに伴う変更点を確認する必要があります。また、発生したビルドエラーの対応策として、Astro.locals.runtimeから環境変数を取得する方法が示されています。さらに、Transitions APIを追加する手順も紹介されています。

個人のポートフォリオサイトをAstroで作っているのですが、メジャーアップデートの対応が漏れていました。いきなりv2からv4にアップグレードした時の作業メモと、起きたエラーの覚書です。

アップグレード前のバージョン

対象サイトの、Astro系ライブラリのバージョンはこんな感じでした。

% cat package.json | jq .dependencies | grep astro 
  "@astrojs/cloudflare": "^6.5.0",
  "@astrojs/rss": "^2.1.1",
  "@astrojs/sitemap": "^1.1.0",
  "@astrojs/tailwind": "^3.1.1",
  "astro": "^2.6.4",

AstroのアップグレードはCLIから

Astroにはアップグレード用のコマンドが用意されています。npx @astrojs/upgradeを実行しましょう。

% npx @astrojs/upgrade
Need to install the following packages:
  @astrojs/[email protected]
Ok to proceed? (y)

対話形式でアップグレードを行うことができます。


 astro   Integration upgrade in progress.

      ▲  astro will be updated to  v4.3.6 
      ▲  @astrojs/cloudflare will be updated to  v9.0.0 
      ▲  @astrojs/rss will be updated to  v4.0.5 
      ▲  @astrojs/sitemap will be updated to  v3.0.5 
      ▲  @astrojs/tailwind will be updated to  v5.1.0 

  wait   Some packages have breaking changes. Continue?
         ● Yes  ○ No

アップグレード中に、「CHANGAELOGを読んでね」と表示されますので、ざっと確認しておくと良さそうです。


 check   Be sure to follow the CHANGELOGs.
         astro Upgrade to Astro v4
         @astrojs/cloudflare CHANGELOG
         @astrojs/rss CHANGELOG
         @astrojs/sitemap CHANGELOG
         @astrojs/tailwind CHANGELOG

このようなメッセージが表示されれば、アップグレード完了です。

      ✔  Installed dependencies!

╭─────╮  Houston:
│ ◠ ◡ ◠  Good luck out there.
╰─────╯

ビルドを試してみる

v2とv4で、ビルドのコマンドには変化がありませんでした。CIに流す前に、手元でビルドしてエラーが起きていないか確認します。

% astro build

発生したビルドエラーと、その対応メモ

対象サイトで発生したエラーは1つでした。すこし変わった組み込みをしている関係で発生したエラーですので、読まれている方が遭遇することはあまりないかもしれません。

Missing “./runtime” specifier in “@astrojs/cloudflare” package [plugin vite:dep-scan]

発生したエラーは、環境変数を取得する部分の処理でした。@astrojs/cloudflareパッケージにあるgetRuntime関数がなくなっていたことが原因で、ビルドがこけました。

import { getRuntime } from "@astrojs/cloudflare/runtime";
import { createClient } from "microcms-js-sdk";
import type { MicroCMSClient } from "./types";

const runtime = getRuntime(Astro.request);
if (runtime && runtime.env) {
    const cfRuntimeAPIKEY = (runtime.env as any).MICROCMS_API_KEY as string
    if (cfRuntimeAPIKEY) {
        return createClient({
            serviceDomain: 'DOMAIN',
            apiKey: cfRuntimeAPIKEY,
        })
    }
}

対応策としてはとてもシンプルで、グローバル変数のAstro.locals.runtimeから環境変数を取得するように変更するだけです。

const runtime = (Astro.locals as any).runtime

ついでにTransitions APIを追加してみた

せっかくなので、v2 -> v4の間に追加されたAPIを一つ追加してみました。レイアウト要素にしている.astroファイルにViewtarnsitionsコンポーネントを追加するだけです。

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

<!-- Global Metadata -->
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<link rel='apple-touch-icon' sizes='180x180' href='/favicons/apple-touch-icon.png' />
<link rel='icon' type='image/png' sizes='32x32' href='/favicons/favicon-32x32.png' />
<link rel='icon' type='image/png' sizes='16x16' href='/favicons/favicon-16x16.png' />
<meta name="generator" content={Astro.generator} />

<ViewTransitions />

あとは、Transitionの動きをつけたい要素に、transition:animate属性を追加すればOKです。


            <main transition:animate="fade">
                <slot></slot>
            </main>

これでページ遷移時のアニメーションが追加できます。