コンテンツにスキップ

Astro v3へのアップグレード

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

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

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

Terminal window
# Astro v3.xにアップグレード
npm install astro@latest
# ReactとTailwindのインテグレーションをアップグレードする例
npm install @astrojs/react@latest @astrojs/tailwind@latest

astro.config.mjsから以下の実験的なフラグを削除します。

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
experimental: {
assets: true,
viewTransitions: true,
},
})

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

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

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

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

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

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

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

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

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

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

.nvmrc
18.14.1

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

Terminal window
npm install typescript@latest --save-dev

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

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

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

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

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

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

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

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

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

src/components/MyAstroComponent.astro
---
import Markdown from '@astrojs/markdown-component';
---

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

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

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の部分的なシム

セクションタイトル: 削除: サーバーコードでのWeb APIの部分的なシム

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

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

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

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

セクションタイトル: 削除: コンテンツコレクションのastro:contentのimage

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

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

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

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

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

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

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

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

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

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

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

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

src/components/MyAstroComponent.astro
---
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変数のケバブケースへの変換

セクションタイトル: 削除: キャメルケースのCSS変数のケバブケースへの変換

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

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

src/components/MyAstroComponent.astro
---
const 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がスタイルをケバブケースへと変換することに依存している場合は、下の例のように既存のスタイルをキャメルケースに更新して、スタイルが失われないようにします。

src/components/MyAstroComponent.astro
<style>
div {
color: var(--my-value);
color: var(--myValue);
}
</style>

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

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/checktypescriptを手動でプロジェクトにインストールしてください。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

セクションタイトル: デフォルトの変更: tsconfig.jsonプリセットのverbatimModuleSyntax

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

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

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

src/components/MyAstroComponent.astro
---
import { type CollectionEntry, getEntry } from "astro:content";
---

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

tsconfig.json
{
"compilerOptions": {
"verbatimModuleSyntax": false
}
}

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のtrailingSlash

Astro v2.xでは、import.meta.env.BASE_URLはデフォルトでbaseの設定値の末尾にスラッシュを追加していました。trailingSlash: "ignore"も末尾にスラッシュを追加していました。

Astro v3.0では、import.meta.env.BASE_URLに末尾のスラッシュを追加しなくなりました。trailingSlash: "ignore"が設定されている場合も同様です。(basetrailingSlash: "always"またはtrailingSlash: "never"を組み合わせた場合の既存動作は変更されていません。)

baseにすでに末尾のスラッシュがある場合は、変更は必要ありません。

baseに末尾のスラッシュがなく、以前のデフォルト(またはtrailingSlash: "ignore")の動作を維持したい場合は、末尾にスラッシュを追加します。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Astro v2.xでは、HTTPリクエストメソッドは、getpostputalldelのように小文字の関数名で書かれていました。

Astro v3.0では、大文字の関数名を使用します。delDELETEとなります。

すべての関数を大文字に変更します。

  • getGET
  • postPOST
  • putPUT
  • allALL
  • delDELETE
endpoint.ts
export function get() {
export function GET() {
return new Response(JSON.stringify({ "title": "Bobのブログ" }));
}

Astro v2.xでは、同じプロジェクトで複数のJSXフレームワークのインテグレーション(React、Solid、Preact)を使用することができましたが、どのファイルがどのフレームワークのものであるかを指定する必要はありませんでした。

Astro v3.0では、複数のJSXフレームワークのインテグレーションがインストールされている場合、どのファイルにどのフレームワークを使用するかを指定するための、includeexcludeという新しいインテグレーション設定オプションを使用する必要があります。これにより、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.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 v2.xでは、"astro"パッケージエントリポイントは、Astro CLIを直接エクスポートして実行していました。この方法でAstroを実行することはおすすめしません。

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

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

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

変更: 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のエントリポイントであり、プロジェクトに影響を与えることはありません。ただし、これらのエントリポイントを使用している場合は、以下のように更新します。

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に関する良い資料をご存知ですか?このページを編集し、以下にリンクを追加してください!

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