Astro v4へのアップグレード

このガイドでは、Astro v3からAstro v4への移行方法について説明します。

古いプロジェクトをv3にアップグレードする必要がありますか？以前の移行ガイドを参照してください。

v3のドキュメントが必要ですか？ドキュメントサイトの以前のバージョン（メンテナンスされていないv3.6のスナップショット）をご覧ください。

Astroをアップグレードする

パッケージマネージャーを使用して、プロジェクトのAstroとすべての公式インテグレーションを最新バージョンに更新します。

# Astroと公式インテグレーションを一緒にアップグレードする
npx @astrojs/upgrade

# Astroと公式インテグレーションを一緒にアップグレードする
pnpm dlx @astrojs/upgrade

# Astroと公式インテグレーションを一緒にアップグレードする
yarn dlx @astrojs/upgrade

必要であれば、Astroインテグレーションの手動アップグレードも可能です。プロジェクトの他の依存関係もアップグレードする必要があるかもしれません。

Astro v4.0は、破壊的な可能性のある変更や、以前に非推奨となっていた機能の削除を含んでいます。

v4.0にアップグレードしたあとプロジェクトが期待どおりに動作しない場合は、このガイドを確認して、すべての破壊的な変更の概要と、コードベースを更新する方法についての手順を確認してください。

完全なリリースノートについては、チェンジログを確認してください。

Astro v4.0の実験的なフラグの削除

astro.config.mjsにおいて、実験的なdevOverlayフラグを削除し、i18nの設定をトップレベルに移動してください。

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    devOverlay: true,
    i18n: {
      defaultLocale: "en",
      locales: ["en", "fr", "pt-br", "es"],
    }
  },
  i18n: {
    defaultLocale: "en",
    locales: ["en", "fr", "pt-br", "es"],
  },
})

これらの設定、i18nとリネームされたdevToolbarは、Astro v4.0で利用可能になりました。

v4.0のブログ記事で、これら2つのエキサイティングな機能の詳細などについて確認してください！

アップグレード

Astroの依存関係のメジャーアップグレードは、プロジェクトに破壊的な変更をもたらす可能性があります。

アップグレード: Vite 5.0

Astro v3.0では、開発サーバーと本番用バンドラーとしてVite 4が使用されていました。

Astro v4.0は、Vite 4をVite 5にアップグレードします。

どうすればいいですか？

Vite固有のプラグインや設定、APIを使用している場合は、Viteの移行ガイドにアクセスして、破壊的な変更を確認し、必要に応じてプロジェクトをアップグレードしてください。Astro自体に対する破壊的な変更はありません。

アップグレード: unified、remarkとrehypeの依存関係

Astro v3.xでは、MarkdownとMDXを処理するために、unified v10およびそれと関連した互換性のあるremark/rehypeパッケージが使用されていました。

Astro v4.0は、unifiedをv11にアップグレードし、その他のremark/rehypeパッケージを最新バージョンにアップグレードします。

どうすればいいですか？

カスタムのremark/rehypeパッケージを使用している場合は、それらがunified v11をサポートするように、パッケージマネージャーを使用してすべてのパッケージを最新バージョンに更新してください。使用しているパッケージはastro.config.mjsで確認できます。

アクティブに更新されているパッケージを使用している場合、大きな破壊的な変更はないはずですが、一部のパッケージはまだunified v11と互換性がないかもしれません。デプロイする前にMarkdown/MDXページを目視して、サイトが意図したとおりに機能しているかどうか確認してください。

破壊的変更

以下の変更は、Astroにおける破壊的な変更と見なされます。破壊的な変更には、一時的な後方互換性がある場合とない場合とがありますが、すべてのドキュメントは、現在サポートされているコードのみを示すように更新されています。

v3.xプロジェクトのドキュメントを参照する必要がある場合は、v4.0がリリースされる前の（メンテナンスされていない）ドキュメントのスナップショットを参照してください。

リネーム: `entrypoint` (インテグレーションAPI)

Astro v3.xでは、ルートのエントリーポイントを指定するインテグレーションAPIinjectRouteのプロパティはentryPointという名前でした。

Astro v4.0は、他のAstro APIとの整合性を保つために、このプロパティをentrypointにリネームします。entryPointプロパティは非推奨ですが、引き続き動作し、使用している場合はコードを更新するように促す警告がログに出力されます。

どうすればいいですか？

injectRoute APIを使用するインテグレーションがある場合は、entryPointプロパティをentrypointにリネームしてください。あなたがAstro 3と4の両方をサポートしたいライブラリの作者である場合は、entryPointとentrypointの両方を指定できます。この場合、警告はログ出力されません。

injectRoute({
  pattern: '/fancy-dashboard',
  entryPoint: '@fancy/dashboard/dashboard.astro'
  entrypoint: '@fancy/dashboard/dashboard.astro'
});

変更: インテグレーションAPIの`app.render`のシグネチャ

Astro v3.0では、app.render()メソッドは、routeDataとlocalsを別々のオプション引数として受け取っていました。

Astro v4.0は、app.render()のシグネチャを変更します。これら2つのプロパティは、単一のオブジェクトにまとめられるようになりました。このオブジェクトと2つのプロパティは、いずれも必須ではありません。

どうすればいいですか？

アダプタをメンテナンスしている場合、現在のシグネチャは次のメジャーバージョンまで引き続き動作します。新しいシグネチャに移行するには、複数の独立した引数としてではなく、routeDataとlocalsをオブジェクトのプロパティとして渡します。

app.render(request, routeData, locals)
app.render(request, { routeData, locals })

変更: アダプターはサポートする機能を指定する必要があります

Astro v3.xでは、アダプターはサポートする機能を指定する必要はありませんでした。

Astro v4.0では、アダプターはサポートする機能のリストを指定するために、supportedAstroFeatures{}プロパティを渡す必要があります。このプロパティは任意ではなくなりました。

どうすればいいですか？

アダプターの作者は、サポートする機能のリストを指定するために、supportedAstroFeatures{}オプションを渡す必要があります。

export default function createIntegration() {
  return {
    name: '@matthewp/my-adapter',
    hooks: {
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@matthewp/my-adapter',
          serverEntrypoint: '@matthewp/my-adapter/server.js',
          supportedAstroFeatures: {
              staticOutput: 'stable'
          }
        });
      },
    },
  };
}

削除: Shiki言語の`path`プロパティ

Astro v3.xでは、markdown.shikiConfig.langsに渡されるShiki言語は、自動的にShikiji互換の言語に変換されました。Shikijiは、Astroが構文のハイライトに使用している内部ツールです。

Astro v4.0は、設定をわかりづらくさせていたShiki言語のpathプロパティのサポートを削除します。これは、langsに直接渡すことができるインポートに置き換えられます。

どうすればいいですか？

言語のJSONファイルをインポートし、オプションに渡します。

 import customLang from './custom.tmLanguage.json'

export default defineConfig({
  markdown: {
    shikiConfig: {
      langs: [
       { path: '../../custom.tmLanguage.json' },
       customLang,
      ],
    },
  },
})

非推奨

以下の非推奨機能へのサポートは終了し、以後はドキュメントの追加もおこなわれません。プロジェクトを適切に更新してください。

一部の非推奨機能は、完全に削除されるまで一時的に機能し続ける場合があります。その他の機能は、単に無効になるか、あるいはコードを更新するように促すエラーが発生します。

非推奨: ビュートランジションの`submit`イベントの`handleForms`

Astro v3.xでは、<ViewTransitions />コンポーネントを使用するプロジェクトは、form要素のsubmitイベントに対する処理を有効にする必要がありました。このためにはhandleFormsプロパティを渡す必要がありました。

Astro v4.0では、<ViewTransitions />を使用すると、form要素のsubmitイベントをデフォルトで処理します。handleFormsプロパティは非推奨となり、何の効果もなくなりました。

どうすればいいですか？

ViewTransitionsコンポーネントからhandleFormsプロパティを削除します。これはもう必要ありません。

---
import { ViewTransitions } from "astro:transitions";
---
<html>
  <head>
    <ViewTransitions handleForms />
  </head>
  <body>
    <!-- 色々 -->
  </body>
</html>

submitイベントの処理を無効にしたい場合は、該当するform要素にdata-astro-reload属性を追加します。

<form action="/contact" data-astro-reload>
  <!-- -->
</form>

以前に非推奨となっていた機能の削除

以下の非推奨機能は、コードベースから完全に削除され、使用できなくなりました。これらの機能の一部は、非推奨となってからもプロジェクトで引き続き機能する可能性があります。他の機能は、単に無効になるかもしれません。

これらの削除された機能を使用しているプロジェクトはビルドできなくなり、機能を削除するよう促すサポートドキュメントはもうありません。

削除: エンドポイントでのプレーンオブジェクトの返却

Astro v3.0では、エンドポイントからプレーンオブジェクトを返すことは非推奨となりましたが、Astro v2との互換性を維持するために引き続きサポートされていました。また、移行を容易にするためにResponseWithEncodingユーティリティも提供されていました。

Astro v4.0では、プレーンオブジェクトのサポートが削除され、エンドポイントは常にResponseを返す必要があります。ResponseWithEncodingユーティリティも適切なResponse型に置き換えられるかたちで削除されています。

どうすればいいですか？

Responseオブジェクトを直接返すようにエンドポイントを更新します。

export async function GET() {
  return { body: { "title": "ボブのブログ" }};
  return new Response(JSON.stringify({ "title": "ボブのブログ" }));
}

ResponseWithEncodingの使用箇所を削除するには、ArrayBufferを使用するようにコードをリファクタリングします。

export async function GET() {
  const file = await fs.readFile('./bob.png');
  return new ResponseWithEncoding(file.toString('binary'), undefined, 'binary');
  return new Response(file.buffer);
}

削除: `build.split`と`build.excludeMiddleware`

Astro v3.0では、build.splitとbuild.excludeMiddlewareのビルド設定オプションは非推奨となり、同じタスクを実行するためにアダプターの設定オプションに置き換えられました。

Astro v4.0では、これらのプロパティは完全に削除されます。

どうすればいいですか？

非推奨のbuild.splitまたはbuild.excludeMiddlewareを使用している場合、これらはもう存在しないため、削除する必要があります。

アダプターの設定でこれらの非推奨のミドルウェアプロパティを更新するためのv3の移行ガイドを参照してください。

削除: `Astro.request.params`

Astro v3.0では、Astro.request.params APIは非推奨となりましたが、後方互換性のために保持されていました。

Astro v4.0では、このオプションは完全に削除されます。

どうすればいいですか？

すべての出現箇所を、サポートされている置き換え先であるAstro.paramsに更新します。

const { id } = Astro.request.params;
const { id } = Astro.params;

削除: `markdown.drafts`

Astro v3.0では、下書きの記事のビルドを制御するためにmarkdown.draftsを使用することは非推奨となりました。

Astro v4.0では、このオプションは完全に削除されます。

どうすればいいですか？

非推奨のmarkdown.draftsを使用している場合、これはもう存在しないため、削除する必要があります。

プロジェクト内の一部のページを下書きとしてマークし続けるには、コンテンツコレクションに移行し、代わりにdraft: trueフロントマタープロパティでページを手動でフィルタリングします。

削除: `getHeaders()`

Astro v3.0では、getHeaders() Markdownのエクスポートは非推奨となり、getHeadings()に置き換えられました。

Astro v4.0では、このオプションは完全に削除されます。

どうすればいいですか？

非推奨のgetHeaders()を使用している場合、これはもう存在しないため、削除する必要があります。サポートされている置き換え先であるgetHeadings()に置き換えてください。

const posts = await Astro.glob('../content/blog/*.mdx');
const firstPostHeadings = posts.at(0).getHeaders();
const firstPostHeadings = posts.at(0).getHeadings();

削除: `getStaticPaths()`における`rss`の使用

Astro v3.0では、getStaticPaths()で非推奨のrssヘルパーを使用するとエラーが発生しました。

Astro v4.0では、このヘルパーは完全に削除されます。

どうすればいいですか？

RSSフィードを生成するためにこのサポートされていないメソッドを使用している場合は、RSSのセットアップに@astrojs/rssインテグレーションを使用する必要があります。

削除: 小文字のHTTPメソッド名

Astro v3.0では、小文字のHTTPリクエストメソッド名（get、post、put、all、del）を使用することは非推奨となりました。

Astro v4.0では、小文字の名前へのサポートは完全に削除されます。すべてのHTTPリクエストメソッドは、大文字を使用して記述する必要があります。

どうすればいいですか？

非推奨の小文字の名前を使用している場合、これらを対応する大文字の名前に置き換える必要があります。

大文字のHTTPリクエストメソッドを使用する方法については、v3の移行ガイドを参照してください。

削除: `base`プレフィックスがない場合の301リダイレクト

Astro v3.xでは、ベースパスがなしでパブリックディレクトリのアセットにアクセスすると、Astroのプレビューサーバーは301リダイレクトを返しました。

Astro v4.0では、プレビューサーバーが実行されている場合、開発サーバーと同じ動作になるように、ベースパスのプレフィックスがない場合にはパブリックディレクトリのアセットに対して404ステータスが返されます。

どうすればいいですか？

Astroのプレビューサーバーを使用する場合、パブリックディレクトリからのすべての静的アセットのインポートとURLには、baseの値がパスの先頭に付けられている必要があります。

以下の例は、base: '/docs'が設定されている場合に、パブリックフォルダから画像を表示するために必要なsrc属性を示しています。

// public/images/my-image.pngにアクセスする:

<img src="/docs/images/my-image.png" alt="">

削除: `astro/client-image`の自動変換

Astro v3.xでは、非推奨の画像インテグレーションで使用されていたastro/client-image型が削除されましたが、env.d.tsファイルでこれが見つかった場合は、デフォルトのAstro型astro/clientに自動変換されました。

Astro v4.0では、astro/client-imageは無視され、env.d.tsは自動的には更新されなくなります。

どうすればいいですか？

src/env.d.tsで@astrojs/imageの型を設定していて、v3.0にアップグレードしても型が自動的に変換されなかった場合は、astro/client-image型をastro/clientに手動で置き換えてください。

  /// <reference types="astro/client-image" />
  /// <reference types="astro/client" />

コミュニティリソース

Astro v4.0に関する良い資料をご存知ですか？このページを編集し、以下にリンクを追加してください！

既知の問題

GitHub上のAstroのissuesで報告済みの問題を確認するか、問題を報告してください。

Astro v4へのアップグレード

Astroをアップグレードする

Astro v4.0の実験的なフラグの削除

アップグレード

アップグレード: Vite 5.0

どうすればいいですか？

アップグレード: unified、remarkとrehypeの依存関係

どうすればいいですか？

破壊的変更

リネーム: entrypoint (インテグレーションAPI)

どうすればいいですか？

変更: インテグレーションAPIのapp.renderのシグネチャ

どうすればいいですか？

変更: アダプターはサポートする機能を指定する必要があります

どうすればいいですか？

削除: Shiki言語のpathプロパティ

どうすればいいですか？

非推奨

非推奨: ビュートランジションのsubmitイベントのhandleForms

どうすればいいですか？

以前に非推奨となっていた機能の削除

削除: エンドポイントでのプレーンオブジェクトの返却

どうすればいいですか？

削除: build.splitとbuild.excludeMiddleware

どうすればいいですか？

削除: Astro.request.params

どうすればいいですか？

削除: markdown.drafts

どうすればいいですか？

削除: getHeaders()

どうすればいいですか？

削除: getStaticPaths()におけるrssの使用

どうすればいいですか？

削除: 小文字のHTTPメソッド名

どうすればいいですか？

削除: baseプレフィックスがない場合の301リダイレクト

どうすればいいですか？

削除: astro/client-imageの自動変換

どうすればいいですか？

コミュニティリソース

既知の問題

リネーム: `entrypoint` (インテグレーションAPI)

変更: インテグレーションAPIの`app.render`のシグネチャ

削除: Shiki言語の`path`プロパティ

非推奨: ビュートランジションの`submit`イベントの`handleForms`

削除: `build.split`と`build.excludeMiddleware`

削除: `Astro.request.params`

削除: `markdown.drafts`

削除: `getHeaders()`

削除: `getStaticPaths()`における`rss`の使用

削除: `base`プレフィックスがない場合の301リダイレクト

削除: `astro/client-image`の自動変換