Astro v3へのアップグレード
このガイドでは、Astro v2からAstro v3への移行方法について説明します。
古いプロジェクトをv2にアップグレードする必要がありますか? 以前の移行ガイドを参照してください。
Astroをアップグレードする
セクションタイトル: Astroをアップグレードするパッケージマネージャーを使用して、プロジェクトのAstroのバージョンを最新に更新します。 Astroのインテグレーションを使用している場合は、そちらも最新バージョンに更新してください。
Astroを最新版にアップグレードしたあと、プロジェクトへの変更が必要とは限りません!
しかし、エラーや予想外の動作が発生した場合は、変更された内容と、プロジェクトを更新する必要があるかどうかを以下で確認してください。
Astro v3の実験的なフラグの削除
セクションタイトル: Astro v3の実験的なフラグの削除astro.config.mjs
から以下の実験的なフラグを削除します。
これらの機能はデフォルトで利用できるようになりました。
- アニメーションによるページ遷移とアイランドを永続化するためのビュートランジション。この実験的なフラグを使用していた場合は、ビュートランジションAPIの変更とアップグレードのアドバイスを参照してください。
- 新しい
<Image />
コンポーネントとgetImage()
関数を含む、Astroで画像を使用するための新しい画像サービスAPIastro:assets
。この実験的なフラグを使用していたかどうかにかかわらず、詳細な画像をアップグレードするためのアドバイスを読んで、プロジェクトへの影響を確認してください。
以上2つのエキサイティングな機能とその他については、3.0のブログ記事を確認してください!
Astro v3の破壊的変更
セクションタイトル: Astro v3の破壊的変更Astro v3.0には、いくつかの破壊的な変更と、以前に非推奨になっていた機能の削除が含まれています。v3.0にアップグレードしたあとプロジェクトが期待通りに動作しない場合はこのガイドを読み、すべての破壊的な変更の概要と、コードベースを更新する方法についての手順を確認してください。
リリースノートの全文については、変更履歴を参照してください。
削除: Node 16のサポート
セクションタイトル: 削除: Node 16のサポートNode 16は2023年9月にサポート終了予定です。
すべてのAstroユーザーがNodeのよりモダンな機能を利用できるようにするため、Astro v3.0ではNode 16のサポートを完全に終了します。
どうすればいいですか?
セクションタイトル: どうすればいいですか?開発環境とデプロイ環境の両方がNode 18.14.1
以上を使用していることを確認してください。
-
ローカルのNodeのバージョンを確認します。
-
デプロイ環境のドキュメントを読み、Node 18がサポートされていることを確認してください。
AstroプロジェクトにNode
18.14.1
を指定するには、ダッシュボードの設定または.nvmrc
ファイルを使用します。
削除: TypeScript 4のサポート
セクションタイトル: 削除: TypeScript 4のサポートAstro v2.xのtsconfig.json
のプリセットでは、TypeScript 4.xと5.xの両方がサポートされていました。
Astro v3.0ではtsconfig.json
のプリセットが更新され、TypeScript 5.xのみをサポートするようになりました。Astroは現在、TypeScript 5.0(2023年3月)を使用しているか、(VS Code 1.77などのように)エディタにTypeScript 5.0が含まれていることを前提とします。
どうすればいいですか?
セクションタイトル: どうすればいいですか?TypeScriptをローカルにインストールしている場合は、v5.0以上に更新してください。
削除: @astrojs/image
セクションタイトル: 削除: @astrojs/imageAstro v2.xでは、Astroは<Image />
や<Picture />
コンポーネントを含む公式の画像インテグレーションを提供していました。
Astro v3.0では、このインテグレーションはコードベースから完全に削除されます。Astroの新しい画像向けソリューションは、組み込みの画像サービスAPIastro:assets
です。
どうすればいいですか?
セクションタイトル: どうすればいいですか?@astrojs/image
インテグレーションをプロジェクトから削除します。インテグレーションをアンインストールするだけでなく、インポート文と、既存の<Image />
と<Picture />
コンポーネントを更新または削除する必要があります。また、デフォルトの画像処理サービスを設定する必要があるかもしれません。
画像のガイドには、古い画像インテグレーションを削除するための完全なステップバイステップの手順が記載されています。
astro:assets
に移行すると、新しい画像オプションや機能が追加されており、これらを使ってみたくなるはずです。詳細については、v3.0の画像アップグレードアドバイスをご覧ください!
削除: <Markdown />
コンポーネント
セクションタイトル: 削除: <Markdown />コンポーネントAstro v1.xで<Markdown />
コンポーネントは非推奨となり、外部パッケージに移動されました。
Astro v3.0では、@astrojs/markdown-component
パッケージは完全に削除されます。Astroの<Markdown />
コンポーネントは、プロジェクトで動作しなくなります。
どうすればいいですか?
セクションタイトル: どうすればいいですか?@astrojs/markdown-component
のすべてのインスタンスを削除します。
コード内で同じような<Markdown />
コンポーネントを引き続き使用するには、astro-remote
などのコミュニティインテグレーションを使用してみてください。インテグレーションのドキュメントに従って、必要に応じて<Markdown />
コンポーネントのインポートと属性を更新してください。
それ以外の場合は、.astro
ファイルからAstroの<Markdown />
コンポーネントのインポートとコンポーネント自体を削除します。コンテンツを直接HTMLとして書き直すか、.md
ファイルからMarkdownをインポートする必要があります。
削除: 非推奨の1.xのAPI
セクションタイトル: 削除: 非推奨の1.xのAPIAstro v1.xでは、初期のAstroの設定値や、<style global>
と<script hoist>
のサポートは非推奨とされました。しかし、これらは後方互換性のためにまだサポートされていました。
Astro v3.0では、これらの非推奨APIは完全に削除されます。公式にサポートされている設定と、モダンな<style is:global>
と<script>
構文を代わりに使用する必要があります。
どうすればいいですか?
セクションタイトル: どうすればいいですか?v1.xのAPIを引き続き使用する場合は、代わりに各機能に対応する新しいAPIを使用してください。
- 非推奨となった設定値については、0.26移行ガイド (EN)を参照してください。
- 非推奨となったscript/style属性については、0.26移行ガイド (EN)を参照してください。
削除: サーバーコードでのWeb APIの部分的なシム
セクションタイトル: 削除: サーバーコードでのWeb APIの部分的なシムAstro v2.xでは、サーバーでレンダリングされるコードでdocument
やlocalStorage
などのWeb APIの部分的なシムが提供されていました。これらのシムは、しばしば不完全で信頼性がありませんでした。
Astro v3.0では、これらの部分的なシムは完全に削除されます。サーバーでレンダリングされるコードではWeb APIは利用できなくなります。
どうすればいいですか?
セクションタイトル: どうすればいいですか?サーバーでレンダリングされるコンポーネントでWeb APIを使用している場合は、それらのAPIを使用している箇所に条件文を追加するか、client:only
クライアントディレクティブを使用する必要があります。
削除: コンテンツコレクションのastro:content
のimage
セクションタイトル: 削除: コンテンツコレクションのastro:contentのimageAstro v2.xでは、コンテンツコレクションAPIは、コンテンツコレクションのスキーマで使用するためにastro:content
からエクスポートしていたimage
を非推奨としました。
Astro v3.0では、このエクスポートは完全に削除されます。
どうすればいいですか?
セクションタイトル: どうすればいいですか?非推奨となったastro:content
のimage()
を使用している場合、これはもう存在しないため削除してください。代わりに、schema
のimage
ヘルパーを使用して画像を検証します。
削除: 0.14以前のShikiのテーマ名
セクションタイトル: 削除: 0.14以前のShikiのテーマ名Astro v2.xでは、Shikiの一部のテーマ名が変更されましたが、後方互換性のためにもとの名前が保持されていました。
Astro v3.0では、変更されたテーマ名を優先し、もとの名前は削除されます。
どうすればいいですか?
セクションタイトル: どうすればいいですか?プロジェクトで以下のテーマのいずれかを使用している場合は、新しい名前に変更してください。
material-darker
->material-theme-darker
material-default
->material-theme
material-lighter
->material-theme-lighter
material-ocean
->material-theme-ocean
material-palenight
->material-theme-palenight
削除: class:list
機能
セクションタイトル: 削除: class:list機能Astro v2.xでは、class:list
ディレクティブは、clsx
に影響されたカスタム実装を使用しており、重複排除やSet
のサポートなど、いくつかの追加機能がありました。
Astro v3.0では、class:list
でclsx
を直接使用するようになり、重複排除やSet
の値はサポートされなくなりました。
どうすればいいですか?
セクションタイトル: どうすればいいですか?class:list
ディレクティブに渡しているSet
要素を、プレーンなArray
に置き換えます。
削除: propとしてのclass:list
の受け渡し
セクションタイトル: 削除: propとしてのclass:listの受け渡しAstro v2.xでは、class:list
の値はAstro.props['class:list']
(EN)を介してコンポーネントに送信されました。
Astro v3.0では、class:list
の値は、Astro.props['class']
を介してコンポーネントに送信される前に、文字列に正規化されます。
どうすればいいですか?
セクションタイトル: どうすればいいですか?class:list
プロパティを受け取ることを期待しているコードを削除します。
削除: キャメルケースのCSS変数のケバブケースへの変換
セクションタイトル: 削除: キャメルケースのCSS変数のケバブケースへの変換Astro v2.xでは、style
属性に渡されたキャメルケースのCSS変数は、(書かれた通りの)キャメルケースと(後方互換性のために必要な)ケバブケースの両方でレンダリングされました。
Astro v3.0では、キャメルケースのCSS変数名のケバブケースへの変換は削除され、もとのキャメルケースのCSS変数のみがレンダリングされます。
どうすればいいですか?
セクションタイトル: どうすればいいですか?Astroがスタイルをケバブケースへと変換することに依存している場合は、下の例のように既存のスタイルをキャメルケースに更新して、スタイルが失われないようにします。
削除: getStaticPaths()
の戻り値の自動フラット化
セクションタイトル: 削除: getStaticPaths()の戻り値の自動フラット化Astro v2.xでは、getStaticPaths()
(EN)の戻り値は、配列の配列を返してもエラーとならないように、自動的にフラット化されていました。
Astro v3.0では、getStaticPaths()
の結果に対する自動フラット化が削除されます。
どうすればいいですか?
セクションタイトル: どうすればいいですか?期待されているオブジェクトの配列ではなく、配列の配列を返している場合は、.flatMap
と.flat
を使用して、フラットな配列を返すようにしてください。
コードを更新する必要がある場合は、getStaticPath()
の戻り値はオブジェクトの配列でなければならないことを示すエラーメッセージが表示されます。
移動: astro check
は外部パッケージが必要になりました
セクションタイトル: 移動: astro checkは外部パッケージが必要になりましたAstro v2.xでは、astro check
はAstroにデフォルトで含まれており、その依存関係はAstroにバンドルされていました。これは、astro check
を使用するかどうかにかかわらず、パッケージが肥大化することを意味していました。また、TypeScriptとAstro Language Serverのバージョンを制御できないという問題もありました。
Astro v3.0では、astro check
コマンドをAstroのコアから外に移動し、外部パッケージ@astrojs/check
が必要になりました。さらに、astro check
コマンドを使用するには、プロジェクトにtypescript
をインストールする必要があります。
どうすればいいですか?
セクションタイトル: どうすればいいですか?Astro v3.0にアップグレードしてastro check
コマンドを実行し、必要な依存関係をインストールしようとするプロンプトに従うか、@astrojs/check
とtypescript
を手動でプロジェクトにインストールしてください。
非推奨: build.excludeMiddleware
とbuild.split
セクションタイトル: 非推奨: build.excludeMiddlewareとbuild.splitAstro v2.xでは、build.excludeMiddleware
とbuild.split
は、SSRモードでアダプターを使用する場合に、特定のファイルがどのように出力されるかを変更するために使用されました。
Astro v3.0では、これらのビルド設定オプションは、edgeMiddleware
とfunctionPerRoute
という、同様のタスクを実行するための新しいSSRアダプター設定オプションに置き換えられます。
どうすればいいですか?
セクションタイトル: どうすればいいですか?Astroの設定ファイルを更新して、アダプターの設定で新しいオプションを直接使用するようにします。
非推奨: markdown.drafts
セクションタイトル: 非推奨: markdown.draftsAstro v2.xでは、markdown.drafts
の設定を使用すると、開発サーバーでは閲覧可能ですが、本番環境ではビルドされないドラフトページを作成できました。
Astro v3.0では、この機能は非推奨となり、代わりにコンテンツコレクションにより手動でドラフトページをフィルタリングする方法が採用されました。これにより、より細かな制御が可能となりました。
どうすればいいですか?
セクションタイトル: どうすればいいですか?プロジェクト内の一部のページをドラフトとして扱い続けるには、コンテンツコレクションに移行し、フロントマターでdraft: true
を使用してページを手動でフィルタリングします。
非推奨: エンドポイントでのプレーンオブジェクトの返却
セクションタイトル: 非推奨: エンドポイントでのプレーンオブジェクトの返却Astro v2.xでは、エンドポイントはプレーンオブジェクトを返すことができ、これはJSONレスポンスに変換されました。
Astro v3.0では、Response
オブジェクトを直接返すことが推奨され、この動作は非推奨となりました。
どうすればいいですか?
セクションタイトル: どうすればいいですか?エンドポイントを更新して、Response
オブジェクトを直接返すようにします。
以前のフォーマットを維持する必要がある場合は、ResponseWithEncoding
オブジェクトを使用できますが、将来的には非推奨となります。
デフォルトの変更: tsconfig.jsonプリセットのverbatimModuleSyntax
セクションタイトル: デフォルトの変更: tsconfig.jsonプリセットのverbatimModuleSyntaxAstro v2.xでは、verbatimModuleSyntax
の設定はデフォルトでオフになっており、これに相当するTypeScript 4.xのimportsNotUsedAsValues
がstrict
プリセットで有効になっていました。
Astro v3.0では、verbatimModuleSyntax
はすべてのプリセットで有効になっています。
どうすればいいですか?
セクションタイトル: どうすればいいですか?このオプションでは、import type
構文を使用して型をインポートする必要があります。
上記のようにtype
を使用して型をインポートすることを推奨しますが、問題が発生する場合は、tsconfig.json
ファイルでverbatimModuleSyntax: false
を設定して無効にすることもできます。
デフォルトの変更: 3000
番ポート
セクションタイトル: デフォルトの変更: 3000番ポートAstro v2.xでは、Astroはデフォルトで3000
番ポートで実行されていました。
Astro v3.0では、デフォルトのポートが4321
に変更されました。🚀
どうすればいいですか?
セクションタイトル: どうすればいいですか?テストやREADME
などでlocalhost:3000
を参照している場合は、新しいポートlocalhost:4321
を反映するように更新します。
デフォルトの変更: import.meta.env.BASE_URLのtrailingSlash
セクションタイトル: デフォルトの変更: import.meta.env.BASE_URLのtrailingSlashAstro v2.xでは、import.meta.env.BASE_URL
はデフォルトでbase
の設定値の末尾にスラッシュを追加していました。trailingSlash: "ignore"
も末尾にスラッシュを追加していました。
Astro v3.0では、import.meta.env.BASE_URL
に末尾のスラッシュを追加しなくなりました。trailingSlash: "ignore"
が設定されている場合も同様です。(base
とtrailingSlash: "always"
またはtrailingSlash: "never"
を組み合わせた場合の既存動作は変更されていません。)
どうすればいいですか?
セクションタイトル: どうすればいいですか?base
にすでに末尾のスラッシュがある場合は、変更は必要ありません。
base
に末尾のスラッシュがなく、以前のデフォルト(またはtrailingSlash: "ignore"
)の動作を維持したい場合は、末尾にスラッシュを追加します。
デフォルトの変更: compressHTML
セクションタイトル: デフォルトの変更: compressHTMLAstro v2.xでは、compressHTML
が明示的にtrue
に設定されている場合にのみ、Astroは出力されたHTMLを圧縮しました。デフォルト値はfalse
でした。
Astro v3.0では、出力されたHTMLをデフォルトで圧縮します。
どうすればいいですか?
セクションタイトル: どうすればいいですか?compressHTML: true
を設定している場合は、これが新しいデフォルトの動作となったため、削除できます。
HTMLの圧縮を無効にするには、compressHTML: false
を設定する必要があります。
デフォルトの変更: scopedStyleStrategy
セクションタイトル: デフォルトの変更: scopedStyleStrategyAstro v2.xでは、scopedStyleStrategy
のデフォルト値は"where"
でした。
Astro v3.0では、新しいデフォルト値"attribute"
が導入されました。デフォルトでは、スタイルはdata-*
属性を使用して適用されます。
どうすればいいですか?
セクションタイトル: どうすればいいですか?プロジェクトで現在のスタイルのスコープを維持するには、設定ファイルを以前のデフォルト値に更新します。
デフォルトの変更: inlineStyleSheets
セクションタイトル: デフォルトの変更: inlineStyleSheetsAstro v2.xでは、プロジェクトのすべてのスタイルシートはデフォルトでリンクタグとして送信されていました。build.inlineStylesheets
の設定を使用して、"always"
で常に<style>
タグにインライン化するか、あるいは"auto"
で一定サイズ以下のスタイルシートのみをインライン化するかを選択できましたが、デフォルトの設定は"never"
でした。
Astro v3.0では、inlineStylesheets
のデフォルト値が"auto"
に変更されました。ViteConfig.build.assetsInlineLimit
(デフォルトは4kb)より小さいスタイルシートはデフォルトでインライン化されます。その他の場合は、プロジェクトのスタイルは外部スタイルシートとして送信されます。
どうすればいいですか?
セクションタイトル: どうすればいいですか?プロジェクトの現在の動作を維持する場合は、build.inlineStylesheets
を以前のデフォルト値"never"
に設定します。
デフォルトの変更: 画像サービス
セクションタイトル: デフォルトの変更: 画像サービスAstro v2.xでは、Squooshがデフォルトの画像処理サービスでした。
Astro v3.0では、デフォルトの画像処理サービスとしてSharpが含まれており、またSquooshを使用するための設定オプションが提供されています。
どうすればいいですか?
セクションタイトル: どうすればいいですか?pnpm
のような厳格なパッケージマネージャーを使用している場合は、Astroの依存関係であるにもかかわらず、プロジェクトにSharpを手動でインストールする必要があるかもしれません。
画像の変換に引き続きSquooshを使用する場合は、次のように設定を更新します。
変更: HTTPリクエストメソッドの大文字小文字
セクションタイトル: 変更: HTTPリクエストメソッドの大文字小文字Astro v2.xでは、HTTPリクエストメソッドは、get
、post
、put
、all
、del
のように小文字の関数名で書かれていました。
Astro v3.0では、大文字の関数名を使用します。del
はDELETE
となります。
どうすればいいですか?
セクションタイトル: どうすればいいですか?すべての関数を大文字に変更します。
get
はGET
post
はPOST
put
はPUT
all
はALL
del
はDELETE
変更: 複数のJSXフレームワークの設定
セクションタイトル: 変更: 複数のJSXフレームワークの設定Astro v2.xでは、同じプロジェクトで複数のJSXフレームワークのインテグレーション(React、Solid、Preact)を使用することができましたが、どのファイルがどのフレームワークのものであるかを指定する必要はありませんでした。
Astro v3.0では、複数のJSXフレームワークのインテグレーションがインストールされている場合、どのファイルにどのフレームワークを使用するかを指定するための、include
とexclude
という新しいインテグレーション設定オプションを使用する必要があります。これにより、Astroは単一フレームワークの使用や、React Fast Refreshなどの高度な機能を上手くサポートできるようになりました。
どうすればいいですか?
セクションタイトル: どうすればいいですか?同じプロジェクトで複数のJSXフレームワークを使用している場合は、include
(また必要があればexclude
)をファイルとフォルダの配列に設定します。ワイルドカードを使用して複数のファイルパスを含めることができます。
/components/react/
や/components/solid/
のように、共通のフレームワークコンポーネントを同じフォルダに配置することをおすすめしますが、これは必須ではありません。
変更: Astro.cookies.get(key)
がundefined
を返すようになりました
セクションタイトル: 変更: Astro.cookies.get(key)がundefinedを返すようになりましたAstro v2.xでは、Astro.cookies.get(key)
(EN)は、クッキーが存在しなくても常にAstroCookie
オブジェクト (EN)を返していました。存在を確認するには、Astro.cookies.has(key)
を使用する必要がありました。
Astro v3.0では、クッキーが存在しない場合、Astro.cookies.get(key)
はundefined
を返します。
どうすればいいですか?
セクションタイトル: どうすればいいですか?Astro.cookies.get(key)
を使用する前にAstro.cookie
オブジェクトの存在を確認しているコードは、この変更によって壊れることはありませんが、存在確認はもう必要ありません。
has()
を使用してAstro.cookies
の値がundefined
かどうかを確認しているコードは、安全に削除できます。
変更: Astro CLIのプログラムでの実行
セクションタイトル: 変更: Astro CLIのプログラムでの実行Astro v2.xでは、"astro"
パッケージエントリポイントは、Astro CLIを直接エクスポートして実行していました。この方法でAstroを実行することはおすすめしません。
Astro v3.0では、CLIをエントリポイントから削除し、dev()
、build()
、preview()
、sync()
などの新しい実験的なJavaScript APIをエクスポートします。
どうすればいいですか?
セクションタイトル: どうすればいいですか?Astro CLIをプログラムで実行する (EN)には、新しい実験的なJavaScript APIを使用します。
変更: Astroの内部APIエントリポイントのエクスポートパス
セクションタイトル: 変更: Astroの内部APIエントリポイントのエクスポートパスAstro v2.xでは、astro/internal/*
とastro/runtime/server/*
からAstroの内部APIをインポートすることができました。
Astro v3.0では、既存のastro/runtime/*
エントリポイントを優先して、2つのエントリポイントを削除しました。さらに、コンパイラ固有のランタイムコードには、新しいastro/compiler-runtime
エクスポートが追加されました。
どうすればいいですか?
セクションタイトル: どうすればいいですか?これらはAstroの内部APIのエントリポイントであり、プロジェクトに影響を与えることはありません。ただし、これらのエントリポイントを使用している場合は、以下のように更新します。
コミュニティリソース
セクションタイトル: コミュニティリソースAstro v3.0に関する良い資料をご存知ですか?このページを編集し、以下にリンクを追加してください!
既知の問題
セクションタイトル: 既知の問題現在、既知の問題はありません。
Upgrade Guides