Astro v4へのアップグレード
このガイドでは、Astro v3からAstro v4への移行方法について説明します。
古いプロジェクトをv3にアップグレードする必要がありますか？以前の移行ガイドを参照してください。
v3のドキュメントが必要ですか？ドキュメントサイトの以前のバージョン（メンテナンスされていないv3.6のスナップショット）をご覧ください。
Astroをアップグレードする
セクションタイトル： 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 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
セクションタイトル： アップグレード: Vite 5.0Astro v3.0では、開発サーバーと本番用バンドラーとしてVite 4が使用されていました。
Astro v4.0は、Vite 4をVite 5にアップグレードします。
どうすればいいですか？
セクションタイトル： どうすればいいですか？Vite固有のプラグインや設定、APIを使用している場合は、Viteの移行ガイドにアクセスして、破壊的な変更を確認し、必要に応じてプロジェクトをアップグレードしてください。Astro自体に対する破壊的な変更はありません。
アップグレード: unified、remarkとrehypeの依存関係
セクションタイトル： アップグレード: 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)
セクションタイトル： リネーム: 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のシグネチャ
セクションタイトル： 変更: インテグレーション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プロパティ
セクションタイトル： 削除: 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
セクションタイトル： 非推奨: ビュートランジションのsubmitイベントのhandleFormsAstro 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
セクションタイトル： 削除: build.splitとbuild.excludeMiddlewareAstro v3.0では、build.splitとbuild.excludeMiddlewareのビルド設定オプションは非推奨となり、同じタスクを実行するためにアダプターの設定オプションに置き換えられました。
Astro v4.0では、これらのプロパティは完全に削除されます。
どうすればいいですか？
セクションタイトル： どうすればいいですか？非推奨のbuild.splitまたはbuild.excludeMiddlewareを使用している場合、これらはもう存在しないため、削除する必要があります。
アダプターの設定でこれらの非推奨のミドルウェアプロパティを更新するためのv3の移行ガイドを参照してください。
削除: Astro.request.params
セクションタイトル： 削除: Astro.request.paramsAstro v3.0では、Astro.request.params APIは非推奨となりましたが、後方互換性のために保持されていました。
Astro v4.0では、このオプションは完全に削除されます。
どうすればいいですか？
セクションタイトル： どうすればいいですか？すべての出現箇所を、サポートされている置き換え先であるAstro.paramsに更新します。
const { id } = Astro.request.params;const { id } = Astro.params;削除: markdown.drafts
セクションタイトル： 削除: markdown.draftsAstro v3.0では、下書きの記事のビルドを制御するためにmarkdown.draftsを使用することは非推奨となりました。
Astro v4.0では、このオプションは完全に削除されます。
どうすればいいですか？
セクションタイトル： どうすればいいですか？非推奨のmarkdown.draftsを使用している場合、これはもう存在しないため、削除する必要があります。
プロジェクト内の一部のページを下書きとしてマークし続けるには、コンテンツコレクションに移行し、代わりにdraft: trueフロントマタープロパティでページを手動でフィルタリングします。
削除: getHeaders()
セクションタイトル： 削除: 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の使用
セクションタイトル： 削除: getStaticPaths()におけるrssの使用Astro v3.0では、getStaticPaths()で非推奨のrssヘルパーを使用するとエラーが発生しました。
Astro v4.0では、このヘルパーは完全に削除されます。
どうすればいいですか？
セクションタイトル： どうすればいいですか？RSSフィードを生成するためにこのサポートされていないメソッドを使用している場合は、RSSのセットアップに@astrojs/rssインテグレーションを使用する必要があります。
削除: 小文字のHTTPメソッド名
セクションタイトル： 削除: 小文字のHTTPメソッド名Astro v3.0では、小文字のHTTPリクエストメソッド名（get、post、put、all、del）を使用することは非推奨となりました。
Astro v4.0では、小文字の名前へのサポートは完全に削除されます。すべてのHTTPリクエストメソッドは、大文字を使用して記述する必要があります。
どうすればいいですか？
セクションタイトル： どうすればいいですか？非推奨の小文字の名前を使用している場合、これらを対応する大文字の名前に置き換える必要があります。
大文字のHTTPリクエストメソッドを使用する方法については、v3の移行ガイドを参照してください。
削除: baseプレフィックスがない場合の301リダイレクト
セクションタイトル： 削除: 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/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で報告済みの問題を確認するか、問題を報告してください。
Upgrade Guides