Astro 6 へのバージョンアップに備えて、実行環境の取り出し方を1か所に集めた

背景

このサイトは Astro 5 で作られています。Astro の公式は、最新バージョンとその一つ前のバージョンしか手入れをしません。最新バージョンが Astro 7 になった今、Astro 5 には安全上の修正も届かなくなりました。そこで、Astro 6、そして Astro 7 へ段階的に上げる準備を始めました。

Astro 6 での大きな変更の一つが、Cloudflare の実行環境を取り出す書き方の廃止です。

Astro 6 用の Cloudflare アダプター（Astro を Cloudflare 上で動かすためのパッケージ @astrojs/cloudflare）では、古い書き方を使うとその場でエラーになります。

問題：書き方が約180ファイルに散らばっていた

調べると、この書き方はサイト中の約180ファイル、約290か所で使われていました。バージョンアップと同時にこれを全部書き換えると、変更が大きくなりすぎます。何か壊れたときに、原因がバージョンアップなのか書き換えなのかを切り分けにくくなります。

対処：取り出し方を共通関数1つに集めた

実行環境を取り出す共通関数 getRuntime() を作りました。

// 実行環境（環境変数・背景処理・接続情報）を取り出す
export function getRuntime(locals) {
  // Astro 5 では locals.runtime に入っている
  const rt = locals?.runtime;
  return { env: rt?.env, ctx: rt?.ctx, cf: rt?.cf };
}

各ファイルでは、実行環境を取り出す1行だけを、この共通関数の呼び出しに置き換えました。

// 前
const { runtime } = Astro.locals;
// 後
const runtime = getRuntime(Astro.locals);

その下にある runtime.env.DB や runtime.ctx?.waitUntil(...) などの使い方は、一切変えていません。返す形を元と同じにしたためです。Astro 6 に上げるときは、getRuntime() の中身だけを新しい書き方に変えれば、サイト全体が新しい書き方に切り替わります。

書き換えは手作業ではなく、決まった形を置き換える小さなスクリプトで行いました。そのうえで、古い書き方が1か所も残っていないことを検索で確かめています。

確かめたこと

• サイト全体のビルドが通ること
• ビルド成果物（ビルドで出来上がったファイル一式）を、本番と同じ実行環境（workerd）に読み込ませて、次を確かめました
  • データベースから値を読む API が、今までどおり値を返すこと
  • 管理画面の入口で、ログインしていなければログイン画面へ戻されること
• 改行コードが CRLF のファイルも、改行コードを崩さずに書き換えたこと

学んだこと

• 外部の仕組みに頼る部分は、最初から1か所を通すように作っておくと、仕組みが変わったときの手直しが小さく済みます
• 大きなバージョンアップは、「バージョンアップの前に、今のバージョンのままでできる書き換え」を先に済ませると、一度に変わる量を減らせます

参考

• Upgrade to Astro v6
• @astrojs/cloudflare（Astro 公式）