Astro v2へのアップグレード

このガイドはAstro v1からAstro v2への移行へ役立ちます。

古いプロジェクトからv1へのアップグレードが必要ですか? 古い移行ガイド (EN)をご覧ください。

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

ターミナルウィンドウ
# Astro v2.xのアップグレード
npm install astro@latest
# 例: ReactとTailwindのインテグレーションをアップグレードする
npm install @astrojs/react@latest @astrojs/tailwind@latest

Astro v2.0では、いくつかの変更点があり、以前廃止された機能が削除されています。もしv2.0にアップグレードした後、プロジェクトが期待通りに動作しない場合、このガイドですべての変更点の概要とコードベースの更新方法を確認してください。

リリースノートの全文は変更履歴をご覧ください。

Node 14は2023年の4月に終了する予定です。

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

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

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

    ターミナルウィンドウ
    node -v

    ローカル環境のアップグレードが必要な場合はNodeをインストールしてください。

  2. デプロイ環境自身のドキュメントを確認し、Node 16をサポートしているかどうかを確認します。

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

Astro v2.0では、MarkdownやMDXファイルをコンテンツコレクションに整理するためのCollections APIが追加されました。このAPIは、src/content/を特別なフォルダとして予約します。

src/content/フォルダの名前を変更し、競合を回避します。このフォルダが存在する場合は、コンテンツコレクションにのみ使用することができるようになりました。

v1.x では、astro.config.mjs で site として設定した URL に Astro.site でアクセスすると、常に末尾にスラッシュが付くようにしました。

Astro v2.0では、siteの値が変更されなくなりました。Astro.siteは定義された正確な値を使用し、必要であれば末尾のスラッシュを指定する必要があります。

astro.config.mjsで、siteに設定したURLの末尾にスラッシュを追加します。

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
site: 'https://example.com',
site: 'https://example.com/',
});

v1.xでは、アセットはassets/chunks/、ビルド出力のルートなど、様々な場所にビルドされていました。

Astro v2.0では、すべてのビルド出力アセットを新しい_astro/フォルダに移動し、場所を統一しています。

  • ディレクトリdist/
    • ディレクトリ_astro
      • client.9218e799.js
      • index.df3f880e0.css

この場所は新しいbuild.assets設定オプションで制御できます。

これらの資産の場所に依存している場合、開発プラットフォームの設定を更新します。

v1.xでは、Astroは独自のMarkdownプラグインを追加する時に、Astroのデフォルトプラグインを再有効化するためにmarkdown.extendDefaultPluginsを使用しました。

Astro v2.0ではこの動作がデフォルトとなったため、この設定オプションを完全に削除しています。

Markdownの設定でremarkとrehypeのプラグインを適用しても、Astroのデフォルトのプラグインを無効にしなくなりました。 GitHub-Flavored Markdown と Smartypants は、カスタムの remarkPluginsrehypePlugins が設定されているかどうかにかかわらず適用されるようになりました。

設定のextendDefaultPluginsを削除してください。これはv2.0のAstroのデフォルトの動作になったので、この行を削除しても差し支えはありません。

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
markdown: {
extendDefaultPlugins,
}
});

v1.xでは、 markdown.extendDefaultPlugins: falseを設定することでAstroのデフォルトMarkdownプラグイン(GitHub-Flavored MarkdownとSmartyPants)の両方を無効化することができました。

Astro v2.0では、markdown.extendDefaultPlugins: falseを、Astroに内蔵されたデフォルトのMarkdownプラグインを個別に制御するブール値のオプションに置き換えました。これらはデフォルトで有効になっており、個別に false に設定できます。

extendDefaultPlugins: falseを削除し、その代わりに各プラグインを個別に無効化するフラグを追加しました。

  • markdown.gfm: false GitHub-Flavored Markdownを無効化する
  • markdown.smartypants: false SmartyPantsを無効化する
astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
markdown: {
extendDefaultPlugins: false,
smartypants: false,
gfm: false,
}
});

置き換え: extendPluginsextendMarkdownConfigへ変更されました。

セクションタイトル: 置き換え: extendPluginsがextendMarkdownConfigへ変更されました。

v1.xでは、MDXインテグレーションのextendPluginsオプションで、MDXファイルがMarkdownの設定をどのように継承するかを管理しました。Markdownの全設定(markdown)、またはAstroのデフォルトプラグインのみ(default)です。

Astro v2.0では、mdx.extendPluginsで制御される動作を、デフォルトでtrueになる3つの新しい独立した設定可能なオプションに置き換えています。

  • mdx.extendMarkdownConfig (EN) を使えば、Markdownの設定のすべてまたは一部を引き継げます。
  • mdx.gfm でMDXのGitHub-Flavored Markdownの有効・無効化を設定します。
  • mdx.smartypants MDXのSmartyPantsの有効・無効化を設定します。

extendPlugins: 'markdown'を設定から削除してください。これで、デフォルトの動作になります。

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

extendPlugins: 'defaults'extendMarkdownConfig: falseに置き換え、GitHub-Flavored MarkdownとSmartyPantsの個別のオプションを追加し、これらのデフォルトプラグインをMDXで個別に有効化します。

astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
integrations: [
mdx({
extendPlugins: 'defaults',
extendMarkdownConfig: false,
smartypants: true,
gfm: true,
}),
],
});

追加: Markdownに対応したMDX設定オプションの追加

セクションタイトル: 追加: Markdownに対応したMDX設定オプションの追加

Astro v2.0では、MDXインテグレーション設定において、利用可能なすべてのMarkdown設定オプションdraftsを除く)を個別に設定できるようになりました。

astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
markdown: {
remarkPlugins: [remarkPlugin1],
gfm: true,
},
integrations: [
mdx({
remarkPlugins: [remarkPlugin2],
gfm: false,
})
]
});

MarkdownとMDXの設定を再検討し、既存の設定と利用可能な新しいオプションを比較します。

変更: フロントマターへのプラグインアクセス

セクションタイトル: 変更: フロントマターへのプラグインアクセス

v1.xでは、remarkとrehypeプラグインはユーザーのフロントマターにアクセスすることができませんでした。Astro はプラグインのフロントマターをファイルのフロントマターにマージし、ファイルのフロントマターをプラグインに渡さないようにしました。

Astro v2.0ではremarkとrehypeプラグインがフロントマターインジェクションを介してユーザーのフロントマターへのアクセスを提供します。これにより、プラグインの作者はユーザーの既存のフロントマターを変更したり、他のプロパティに基づいて新しいプロパティを計算したりすることができます。

あなたが書いたremarkやrehypeプラグインの動作が変わったかどうか確認してください。data.astro.frontmatterは空のオブジェクトではなく、完全なMarkdownまたはMDXドキュメントのフロントマターになったことに注意してください。

v1.xでは、AstroのRSSパッケージは、items: import.meta.glob(...)を使って、RSSフィードアイテムのリストを生成することができました。この使い方は現在非推奨であり、いずれ削除される予定です。

Astro v2.0では、itemsプロパティにpagesGlobToRssItems()が導入されました。

import.meta.glob()を含む既存の関数をpagesGlobToRssItems()ヘルパーでラップしてください。

src/pages/rss.xml.js
import rss, {
pagesGlobToRssItems
} from '@astrojs/rss';
export async function get(context) {
return rss({
items: await pagesGlobToRssItems(
import.meta.glob('./blog/*.{md,mdx}'),
),
});
}

Astro v2.0では、@astrojs/svelteインテグレーション (EN)を使用する場合、プロジェクトにsvelte.config.jsファイルが必要です。これはIDEの自動補完を提供するために必要です。

プロジェクトのルートにsvelte.config.jsファイルを追加します。

svelte.config.js
import { vitePreprocess } from '@astrojs/svelte';
export default {
preprocess: vitePreprocess(),
};

新規ユーザーの場合、astro add svelteを実行すると、このファイルが自動的に追加されます。

v1.0では、Astroは古いastroFlavored Markdown(Components in Markdownとしても知られている)をレガシ機能へ移行しました。

Astro v2.0では、legacy.astroFlavoredMarkdown オプションは完全に削除されました。.mdファイル内のコンポーネントをインポートして使うことはできなくなります。

このレガシーフラグを削除します。 Astroでは使用できなくなりました。

astro.config.mjs
export default defineConfig({
legacy: {
astroFlavoredMarkdown: true,
},
})

v1.x でこの機能を使用していた場合は、MDXインテグレーション (EN)を使用することをお勧めします。これにより、コンポーネントとJSX式をMarkdown構文で組み合わせることができます。

v0.24では、Astroは、ブラウザーで参照する可能性があるアセットへの解決済みURLを取得するための Astro.resolve() を非推奨にしました。

Astro v2.0では、このオプションが完全に削除されています。あなたのコードでAstro.resolve()を使用すると、エラーが発生します。

アセットパスの解決は、代わりにimportを使用します。例えば、次のようになります。

src/pages/index.astro
---
import 'style.css';
import imageUrl from './image.png';
---
<img src={imageUrl} />

v0.26では、ローカルのMarkdownファイルからデータを取得するためのAstro.fetchContent()を非推奨にしました。

Astro v2.0では、このオプションは完全に削除されています。あなたのコードでAstro.fetchContent()を実行すると、エラーになります。

Astro.glob()を使ってローカルのMarkdownファイルを取得したり、コンテンツコレクションに変換したりできます。

src/pages/index.astro
---
const allPosts = await Astro.glob('./posts/*.md');
---

v1.0 では、Astroは正規のURLを構築するためのAstro.canonicalURLを非推奨にしました。

Astro v2.0では、このオプションは完全に削除されています。あなたのコードでAstro.canonicalURLを実行すると、エラーになります。

Astro.urlを使用して、正規のURLを構築します。

src/pages/index.astro
---
const canonicalURL = new URL(Astro.url.pathname, Astro.site);
---

Astro v2.0は、2022年12月にリリースされたVite 3からVite 4にアップグレードします。

コードの変更は必要ありません。Astro内部でほとんどのアップグレードに対応しました。ただし、Viteの微妙な動作はバージョンによって変化することがあります。

問題が発生した場合は、公式のVite移行ガイドを参照してください。

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

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

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

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