import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

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

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

Astroをアップグレードする

パッケージマネージャーを使用して、プロジェクトのAstroのバージョンを最新に更新します。 Astroのインテグレーションを使用している場合は、そちらも最新バージョンに更新してください。

ReactとTailwindのインテグレーションをアップグレードする例

npm install @astrojs/react@latest @astrojs/tailwind@latest

ReactとTailwindのインテグレーションをアップグレードする例

yarn add @astrojs/react@latest @astrojs/tailwind@latest

これらの機能はデフォルトで利用できるようになりました。

• アニメーションによるページ遷移とアイランドを永続化するためのビュートランジション。
• 新しい<Image />コンポーネントとgetImage()関数を含む、Astroで画像を使用するための新しい画像サービスAPIastro:assets。この実験的なフラグを使用していたかどうかにかかわらず、詳細な画像をアップグレードするためのアドバイスを読んで、プロジェクトへの影響を確認してください。

以上2つのエキサイティングな機能とその他については、3.0のブログ記事を確認してください！

Astro v3の破壊的変更

Astro v3.0には、いくつかの破壊的な変更と、以前に非推奨になっていた機能の削除が含まれています。v3.0にアップグレードしたあとプロジェクトが期待通りに動作しない場合はこのガイドを読み、すべての破壊的な変更の概要と、コードベースを更新する方法についての手順を確認してください。

リリースノートの全文については、変更履歴を参照してください。

削除: Node 16のサポート

Node 16は2023年9月にサポート終了予定です。

すべてのAstroユーザーがNodeのよりモダンな機能を利用できるようにするため、Astro v3.0ではNode 16のサポートを完全に終了します。

どうすればいいですか？

開発環境とデプロイ環境の両方がNode 18.14.1以上を使用していることを確認してください。

1. ローカルのNodeのバージョンを確認します。

   sh

   コードをコピー

   コードをクリップボードにコピー

   node -v

2. デプロイ環境のドキュメントを読み、Node 18がサポートされていることを確認してください。

   AstroプロジェクトにNode 18.14.1を指定するには、ダッシュボードの設定または.nvmrcファイルを使用します。

   bash

   コードをコピー

   コードをクリップボードにコピー

   18.14.1

削除: 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以上に更新してください。

npm install typescript@latest --save-dev

削除: @astrojs/image

Astro v2.xでは、Astroは<Image />や<Picture />コンポーネントを含む公式の画像インテグレーションを提供していました。

Astro v3.0では、このインテグレーションはコードベースから完全に削除されます。Astroの新しい画像向けソリューションは、組み込みの画像サービスAPIastro:assetsです。

どうすればいいですか？

@astrojs/imageインテグレーションをプロジェクトから削除します。インテグレーションをアンインストールするだけでなく、インポート文と、既存の<Image />と<Picture />コンポーネントを更新または削除する必要があります。また、デフォルトの画像処理サービスを設定する必要があるかもしれません。

画像のガイドには、古い画像インテグレーションを削除するための完全なステップバイステップの手順が記載されています。

astro:assetsに移行すると、新しい画像オプションや機能が追加されており、これらを使ってみたくなるはずです。詳細については、v3.0の画像アップグレードアドバイスをご覧ください！

// astro.config.mjsimport { defineConfig } from 'astro/config';import image from '@astrojs/image';export default defineConfig({  integrations: [    image(),  ]})

削除: <Markdown />コンポーネント

Astro v1.xで<Markdown />コンポーネントは非推奨となり、外部パッケージに移動されました。

Astro v3.0では、@astrojs/markdown-componentパッケージは完全に削除されます。Astroの<Markdown />コンポーネントは、プロジェクトで動作しなくなります。

どうすればいいですか？

@astrojs/markdown-componentのすべてのインスタンスを削除します。

---import Markdown from '@astrojs/markdown-component';---

コード内で同じような<Markdown />コンポーネントを引き続き使用するには、astro-remoteなどのコミュニティインテグレーションを使用してみてください。インテグレーションのドキュメントに従って、必要に応じて<Markdown />コンポーネントのインポートと属性を更新してください。

それ以外の場合は、.astroファイルからAstroの<Markdown />コンポーネントのインポートとコンポーネント自体を削除します。コンテンツを直接HTMLとして書き直すか、.mdファイルからMarkdownをインポートする必要があります。

削除: 非推奨の1.xのAPI

Astro v1.xでは、初期のAstroの設定値や、<style global>と<script hoist>のサポートは非推奨とされました。しかし、これらは後方互換性のためにまだサポートされていました。

Astro v3.0では、これらの非推奨APIは完全に削除されます。公式にサポートされている設定と、モダンな<style is:global>と<script>構文を代わりに使用する必要があります。

どうすればいいですか？

v1.xのAPIを引き続き使用する場合は、代わりに各機能に対応する新しいAPIを使用してください。

• 非推奨となった設定値については、0.26移行ガイドを参照してください。
• 非推奨となったscript/style属性については、0.26移行ガイドを参照してください。

削除: サーバーコードでのWeb APIの部分的なシム

Astro v2.xでは、サーバーでレンダリングされるコードでdocumentやlocalStorageなどのWeb APIの部分的なシムが提供されていました。これらのシムは、しばしば不完全で信頼性がありませんでした。

Astro v3.0では、これらの部分的なシムは完全に削除されます。サーバーでレンダリングされるコードではWeb APIは利用できなくなります。

どうすればいいですか？

サーバーでレンダリングされるコンポーネントでWeb APIを使用している場合は、それらのAPIを使用している箇所に条件文を追加するか、client:onlyクライアントディレクティブを使用する必要があります。

削除: コンテンツコレクションのastro:contentのimage

Astro v2.xでは、コンテンツコレクションAPIは、コンテンツコレクションのスキーマで使用するためにastro:contentからエクスポートしていたimageを非推奨としました。

Astro v3.0では、このエクスポートは完全に削除されます。

どうすればいいですか？

非推奨となったastro:contentのimage()を使用している場合、これはもう存在しないため削除してください。代わりに、schemaのimageヘルパーを使用して画像を検証します。

import { defineCollection, z, image } from "astro:content";import { defineCollection, z } from "astro:content";defineCollection({  schema: ({ image }) =>    z.object({      image: image(),   }),});

削除: 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機能

Astro v2.xでは、class:listディレクティブは、clsxに影響されたカスタム実装を使用しており、重複排除やSetのサポートなど、いくつかの追加機能がありました。

Astro v3.0では、class:listでclsxを直接使用するようになり、重複排除やSetの値はサポートされなくなりました。

どうすればいいですか？

class:listディレクティブに渡しているSet要素を、プレーンなArrayに置き換えます。

<Component class:list={[  'a',  'b',  new Set(['c', 'd'])  ['c', 'd'] ]} />

削除: propとしてのclass:listの受け渡し

Astro v2.xでは、class:listの値はAstro.props['class:list']を介してコンポーネントに送信されました。

Astro v3.0では、class:listの値は、Astro.props['class']を介してコンポーネントに送信される前に、文字列に正規化されます。

どうすればいいですか？

class:listプロパティを受け取ることを期待しているコードを削除します。

---import { clsx } from 'clsx';const { class: className, 'class:list': classList } = Astro.props;const { class: className } = Astro.props;---<div  class:list={[className, classList]}  class:list={[className]}/>

削除: キャメルケースのCSS変数のケバブケースへの変換

Astro v2.xでは、style属性に渡されたキャメルケースのCSS変数は、（書かれた通りの）キャメルケースと（後方互換性のために必要な）ケバブケースの両方でレンダリングされました。

Astro v3.0では、キャメルケースのCSS変数名のケバブケースへの変換は削除され、もとのキャメルケースのCSS変数のみがレンダリングされます。

---// src/components/MyAstroComponent.astroconst myValue = "red"---<!-- 入力 --><div style={{ "--myValue": myValue }}></div><!-- Astro 2.xの出力 --><div style="--my-value:var(--myValue);--myValue:red"></div><!-- Astro 3.0の出力 --><div style="--myValue:red"></div>

どうすればいいですか？

Astroがスタイルをケバブケースへと変換することに依存している場合は、下の例のように既存のスタイルをキャメルケースに更新して、スタイルが失われないようにします。

<style>  div {   color: var(--my-value);   color: var(--myValue);  }</style>

削除: getStaticPaths()の戻り値の自動フラット化

Astro v2.xでは、getStaticPaths()の戻り値は、配列の配列を返してもエラーとならないように、自動的にフラット化されていました。

Astro v3.0では、getStaticPaths()の結果に対する自動フラット化が削除されます。

どうすればいいですか？

期待されているオブジェクトの配列ではなく、配列の配列を返している場合は、.flatMapと.flatを使用して、フラットな配列を返すようにしてください。

コードを更新する必要がある場合は、getStaticPath()の戻り値はオブジェクトの配列でなければならないことを示すエラーメッセージが表示されます。

移動: 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

Astro v2.xでは、build.excludeMiddlewareとbuild.splitは、SSRモードでアダプターを使用する場合に、特定のファイルがどのように出力されるかを変更するために使用されました。

Astro v3.0では、これらのビルド設定オプションは、edgeMiddlewareとfunctionPerRouteという、同様のタスクを実行するための新しいSSRアダプター設定オプションに置き換えられます。

どうすればいいですか？

Astroの設定ファイルを更新して、アダプターの設定で新しいオプションを直接使用するようにします。

import { defineConfig } from "astro/config";import vercel from "@astrojs/vercel/serverless";export default defineConfig({    build: {      excludeMiddleware: true    },    adapter: vercel({      edgeMiddleware: true    }),});

import { defineConfig } from "astro/config";import netlify from "@astrojs/netlify/functions";export default defineConfig({     build: {        split: true     },     adapter: netlify({        functionPerRoute: true     }),});

非推奨: markdown.drafts

Astro v2.xでは、markdown.draftsの設定を使用すると、開発サーバーでは閲覧可能ですが、本番環境ではビルドされないドラフトページを作成できました。

Astro v3.0では、この機能は非推奨となり、代わりにコンテンツコレクションにより手動でドラフトページをフィルタリングする方法が採用されました。これにより、より細かな制御が可能となりました。

どうすればいいですか？

プロジェクト内の一部のページをドラフトとして扱い続けるには、コンテンツコレクションに移行し、フロントマターでdraft: trueを使用してページを手動でフィルタリングします。

非推奨: エンドポイントでのプレーンオブジェクトの返却

Astro v2.xでは、エンドポイントはプレーンオブジェクトを返すことができ、これはJSONレスポンスに変換されました。

Astro v3.0では、Responseオブジェクトを直接返すことが推奨され、この動作は非推奨となりました。

どうすればいいですか？

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

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

以前のフォーマットを維持する必要がある場合は、ResponseWithEncodingオブジェクトを使用できますが、将来的には非推奨となります。

export async function GET() {  return { body: { "title": "Bob's blog" } };  return new ResponseWithEncoding({ body: { "title": "Bob's blog" }});}

デフォルトの変更: tsconfig.jsonプリセットのverbatimModuleSyntax

Astro v2.xでは、verbatimModuleSyntaxの設定はデフォルトでオフになっており、これに相当するTypeScript 4.xのimportsNotUsedAsValuesがstrictプリセットで有効になっていました。

Astro v3.0では、verbatimModuleSyntaxはすべてのプリセットで有効になっています。

どうすればいいですか？

このオプションでは、import type構文を使用して型をインポートする必要があります。

---import { type CollectionEntry, getEntry } from "astro:content";---

上記のようにtypeを使用して型をインポートすることを推奨しますが、問題が発生する場合は、tsconfig.jsonファイルでverbatimModuleSyntax: falseを設定して無効にすることもできます。

{  "compilerOptions": {    "verbatimModuleSyntax": false  }}

デフォルトの変更: 3000番ポート

Astro v2.xでは、Astroはデフォルトで3000番ポートで実行されていました。

{/* cli-referenceを更新したらリンク先を#--port-numberにする */}

Astro v3.0では、デフォルトのポートが4321に変更されました。🚀

どうすればいいですか？

テストやREADMEなどでlocalhost:3000を参照している場合は、新しいポートlocalhost:4321を反映するように更新します。

デフォルトの変更: import.meta.env.BASE_URLのtrailingSlash

Astro 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"）の動作を維持したい場合は、末尾にスラッシュを追加します。

import { defineConfig } from "astro/config";export default defineConfig({  base: 'my-base',  base: 'my-base/',});

デフォルトの変更: compressHTML

{/* configuration-referenceを更新したらリンク先を#compresshtmlにする */}

Astro v2.xでは、compressHTMLが明示的にtrueに設定されている場合にのみ、Astroは出力されたHTMLを圧縮しました。デフォルト値はfalseでした。

Astro v3.0では、出力されたHTMLをデフォルトで圧縮します。

どうすればいいですか？

compressHTML: trueを設定している場合は、これが新しいデフォルトの動作となったため、削除できます。

import { defineConfig } from "astro/config";export default defineConfig({  compressHTML: true})

HTMLの圧縮を無効にするには、compressHTML: falseを設定する必要があります。

デフォルトの変更: scopedStyleStrategy

{/* configuration-referenceを更新したらリンク先を#scopedstylestrategyにする */}

Astro v2.xでは、scopedStyleStrategyのデフォルト値は"where"でした。

Astro v3.0では、新しいデフォルト値"attribute"が導入されました。デフォルトでは、スタイルはdata-*属性を使用して適用されます。

どうすればいいですか？

プロジェクトで現在のスタイルのスコープを維持するには、設定ファイルを以前のデフォルト値に更新します。

import { defineConfig } from "astro/config";export default defineConfig({  scopedStyleStrategy: "where"})

デフォルトの変更: inlineStyleSheets

{/* configuration-referenceを更新したらリンク先を#buildinlinestylesheetsにする */}

Astro v2.xでは、プロジェクトのすべてのスタイルシートはデフォルトでリンクタグとして送信されていました。build.inlineStylesheetsの設定を使用して、"always"で常に<style>タグにインライン化するか、あるいは"auto"で一定サイズ以下のスタイルシートのみをインライン化するかを選択できましたが、デフォルトの設定は"never"でした。

Astro v3.0では、inlineStylesheetsのデフォルト値が"auto"に変更されました。ViteConfig.build.assetsInlineLimit（デフォルトは4kb）より小さいスタイルシートはデフォルトでインライン化されます。その他の場合は、プロジェクトのスタイルは外部スタイルシートとして送信されます。

どうすればいいですか？

プロジェクトの現在の動作を維持する場合は、build.inlineStylesheetsを以前のデフォルト値"never"に設定します。

import { defineConfig } from "astro/config";export default defineConfig({	 build: {    inlineStylesheets: "never"  }})

デフォルトの変更: 画像サービス

Astro v2.xでは、Squooshがデフォルトの画像処理サービスでした。

Astro v3.0では、デフォルトの画像処理サービスとしてSharpが含まれており、またSquooshを使用するための設定オプションが提供されています。

どうすればいいですか？

:::note pnpmのような厳格なパッケージマネージャーを使用している場合は、Astroの依存関係であるにもかかわらず、プロジェクトにSharpを手動でインストールする必要があるかもしれません。

pnpm add sharp

:::

画像の変換に引き続きSquooshを使用する場合は、次のように設定を更新します。

import { defineConfig, squooshImageService } from "astro/config";export default defineConfig({  image: {    service: squooshImageService(),  }})

変更: 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

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

変更: 複数の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/のように、共通のフレームワークコンポーネントを同じフォルダに配置することをおすすめしますが、これは必須ではありません。

import { defineConfig } from 'astro/config';import preact from '@astrojs/preact';import react from '@astrojs/react';import svelte from '@astrojs/svelte';import vue from '@astrojs/vue';import solid from '@astrojs/solid-js';export default defineConfig({  // 複数のフレームワークを有効にして、さまざまな種類のコンポーネントをサポートします。  // 単一のフレームワークのみを使用している場合、`include`は必要ありません！  integrations: [    preact({      include: ['**/preact/*']    }),    react({      include: ['**/react/*']    }),    solid({      include: ['**/solid/*'],    }),  ]});

変更: Astro.cookies.get(key)がundefinedを返すようになりました

Astro v2.xでは、Astro.cookies.get(key)は、クッキーが存在しなくても常にAstroCookieオブジェクトを返していました。存在を確認するには、Astro.cookies.has(key)を使用する必要がありました。

Astro v3.0では、クッキーが存在しない場合、Astro.cookies.get(key)はundefinedを返します。

どうすればいいですか？

Astro.cookies.get(key)を使用する前にAstro.cookieオブジェクトの存在を確認しているコードは、この変更によって壊れることはありませんが、存在確認はもう必要ありません。

has()を使用してAstro.cookiesの値がundefinedかどうかを確認しているコードは、安全に削除できます。

if (Astro.cookies.has(id)) {  const id = Astro.cookies.get(id)!;}const id = Astro.cookies.get(id);if (id) {}

変更: Astro CLIのプログラムでの実行

Astro v2.xでは、"astro"パッケージエントリポイントは、Astro CLIを直接エクスポートして実行していました。この方法でAstroを実行することはおすすめしません。

Astro v3.0では、CLIをエントリポイントから削除し、dev()、build()、preview()、sync()などの新しい実験的なJavaScript APIをエクスポートします。

どうすればいいですか？

{/* cli-referenceを更新したらリンク先を#advanced-apis-experimentalにする */}

Astro CLIをプログラムで実行するには、新しい実験的なJavaScript APIを使用します。

import { dev, build } from "astro";// Astroの開発サーバーを起動するconst devServer = await dev();await devServer.stop();// Astroプロジェクトをビルドするawait build();

変更: Astroの内部APIエントリポイントのエクスポートパス

Astro v2.xでは、astro/internal/*とastro/runtime/server/*からAstroの内部APIをインポートすることができました。

Astro v3.0では、既存のastro/runtime/*エントリポイントを優先して、2つのエントリポイントを削除しました。さらに、コンパイラ固有のランタイムコードには、新しいastro/compiler-runtimeエクスポートが追加されました。

どうすればいいですか？

これらはAstroの内部APIのエントリポイントであり、プロジェクトに影響を与えることはありません。ただし、これらのエントリポイントを使用している場合は、以下のように更新します。

import 'astro/internal/index.js';import 'astro/runtime/server/index.js';import 'astro/server/index.js';import 'astro/runtime/server/index.js';

import { transform } from '@astrojs/compiler';const result = await transform(source, {  internalURL: 'astro/runtime/server/index.js',  internalURL: 'astro/compiler-runtime',  // ...});

コミュニティリソース

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

既知の問題

現在、既知の問題はありません。