import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' import { FileTree } from '@astrojs/starlight/components';

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

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

Astroをアップグレードする

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

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

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

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

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

変更: ビルドアセット用の_astro/フォルダー

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

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

どうすればいいの？

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

変更: Markdownプラグインの設定

削除: extendDefaultPlugins

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

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

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

どうすればいいの？

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

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

追加: gfmとsmartypants

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.mjsimport { defineConfig } from 'astro/config';export default defineConfig({  markdown: {    extendDefaultPlugins: false,    smartypants: false,    gfm: false,  }});

変更: MDXプラグイン設定

置き換え: extendPluginsがextendMarkdownConfigへ変更されました。

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

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

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

どうすればいいの？

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

// astro.config.mjsimport { 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.mjsimport { defineConfig } from 'astro/config';import mdx from '@astrojs/mdx';export default defineConfig({  integrations: [    mdx({      extendPlugins: 'defaults',      extendMarkdownConfig: false,      smartypants: true,      gfm: true,    }),  ],});

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

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

// astro.config.mjsimport { 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ドキュメントのフロントマターになったことに注意してください。

変更: RSSの構成

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

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

どうすればいいの？

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

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

変更: Svelte IDEのサポート

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

どうすればいいの？

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

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

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

削除: legacy.astroFlavoredMarkdown

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

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

どうすればいいの？

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

// astro.config.mjsexport default defineConfig({	legacy: {		astroFlavoredMarkdown: true,	},})

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

削除: Astro.resolve()

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} />

削除: Astro.fetchContent()

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

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

どうすればいいの？

{/* TODO: Set anchor link from #その他のアセット to #astroglob */} Astro.glob()を使ってローカルのMarkdownファイルを取得したり、コンテンツコレクションに変換したりできます。

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

更新: Astro.canonicalURL

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);---

更新: Vite 4

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

どうすればいいの？

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

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

Astro v2.0 実験用フラグを削除しました。

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

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

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

• MarkdownやMDXのファイルを型安全で管理する方法として、コンテンツコレクションがあります。
• SSR使用時に個別ページ静的HTMLにプリレンダリングをし、高速化とキャッシュ性能の向上を図る。
• エラーメッセージのオーバーレイのデザインを変更しました。

既知の問題点

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