Astro v7へのアップグレード

このプロンプトをコピーしてプロジェクトをアップグレードしてください:

Upgrade my Astro project to v7. Follow the migration guide at
https://docs.astro.build/en/guides/upgrade-to/v7/

このガイドでは、Astro v6からAstro v7への移行方法を説明します。

先にv6へのアップグレードが必要ですか？以前の移行ガイドを確認してください。

v6のドキュメントが必要ですか？以前のバージョンのドキュメントサイト（メンテナンスされていないv6のスナップショット）を確認してください。

Astroのアップグレード

パッケージマネージャーを使用して、プロジェクトのAstroを最新バージョンに更新します。

# Astroと公式インテグレーションをまとめてアップグレード
npx @astrojs/upgrade

# Astroと公式インテグレーションをまとめてアップグレード
pnpm dlx @astrojs/upgrade

# Astroと公式インテグレーションをまとめてアップグレード
yarn dlx @astrojs/upgrade

必要に応じてAstroインテグレーションを手動でアップグレード (EN)することもできます。また、プロジェクト内の他の依存関係のアップグレードが必要になる場合もあります。

Astro v7.0には、破壊的な変更の可能性がある項目に加え、以前に非推奨となった一部の機能の削除が含まれています。

v7.0へのアップグレード後にプロジェクトが期待どおりに動作しない場合は、このガイドで破壊的な変更の概要とコードベースの更新手順を確認してください。

完全なリリースノートについてはAstroのchangelogを見てください。

破壊的な変更

依存関係のアップグレード

Vite 8

Astro v7.0では、開発サーバーおよびプロダクションバンドラーとして使用するViteがv8にアップグレードされました。

どうすればよいですか？

Vite固有のプラグイン、設定、またはAPIを使用している場合は、Vite 8の移行ガイドで破壊的な変更を確認し、必要に応じてプロジェクトをアップグレードしてください。

ほとんどのAstroユーザーは、プロジェクトのコードを変更することなくアップグレードできるはずです。これは主に、Viteの内部に依存するAstroのインテグレーションやプラグインに対する破壊的な変更です。

実験的フラグ

実験的フラグを使用すると、開発の初期段階にある機能をオプトインで利用できます。以下の実験的フラグはAstro 7.0で削除され、安定版または新しいデフォルトの動作になりました。

これらの実験的フラグを以前に使用していた場合は、Astroの設定から削除してください。

import { defineConfig, logHandlers, memoryCache } from 'astro/config';

export default defineConfig({
  experimental: {
    logger: logHandlers.json({ pretty: true }),
    queuedRendering: {
      enabled: true,
    },
    rustCompiler: true,
    advancedRouting: true,
    cache: {
      provider: memoryCache(),
    },
    routeRules: {
      '/blog/[...path]': { maxAge: 300, swr: 60 },
    },
  },
  cache: {
    provider: memoryCache(),
  },
  routeRules: {
    '/blog/[...path]': { maxAge: 300, swr: 60 },
  },
})

安定版になった実験的機能:

logger: 新しいロギングシステムが安定版になり、使用するために実験的フラグが不要になりました。このフラグを使用していた場合は、Astro設定のトップレベルのloggerフィールドにロガーを直接設定できるようになりました。
queuedRendering: キューによるレンダリング（queued rendering）がデフォルトの動作になり、実験的フラグは削除されました。この機能をプロジェクトで有効にするための操作は不要です。すべてのプロジェクトがパフォーマンスの向上の恩恵を受けられるようになりました。
rustCompiler: RustベースのAstroコンパイラがデフォルトかつ唯一のコンパイラとなり、従来のGoベースのコンパイラを置き換えました。プロジェクトに影響を与える可能性のある動作の変更点の詳細については、Rustコンパイラを確認してください。
advancedRouting: 高度なルーティングがデフォルトで有効になりました。詳細については高度なルーティングのガイド (EN)を確認してください。なお、src/fetch.tsは予約済みのファイル名になりました。
cache: ルートキャッシュが安定版になりました。この機能を使用していた場合は、cacheとrouteRulesをexperimentalブロックの外に移動するよう設定を更新してください。

Rustコンパイラ

実装PR：feat!: make Rust compiler the default and only compiler (#16462)

Astro v7.0では、従来のGoベースのコンパイラが新しいRustベースのコンパイラに置き換えられました。新しいコンパイラはより高速ですが、無効なHTML構文に対してより厳格でもあります。以前はエラーなくビルドできていたテンプレートが、失敗するようになる場合があります。

Rustコンパイラには、2つの重要な変更点があります。

閉じられていないタグがエラーになります。 従来のコンパイラは、閉じられていないHTMLタグやコンポーネントタグを暗黙的に受け入れていました。Rustコンパイラでは、すべての非空要素（non-void要素）に対応する閉じタグが必要です。
意味的に無効なHTMLが自動修正されなくなります。 従来のコンパイラは、HTMLのパース仕様に合わせて、無効なHTMLを暗黙的に並べ替えたり再構成したりしていました（例：ブロック要素が許可されていない<p>タグの外に要素を移動するなど）。Rustコンパイラはマークアップを修正しようとせず、そのまま通過させてブラウザに処理を委ねます。これにより、以前は「許容」されていた無効なマークアップのレンダリング結果が変わる場合があります。

どうすればよいですか？

アップグレード後にビルドを実行してください。予期しないトークンや閉じられていないタグに関するコンパイラエラーが表示された場合は、不足している閉じタグを追加してください:

<!-- 変更前: Goコンパイラが暗黙的に受け入れていた閉じられていないタグ -->
<p>Hello world
<p>Hello world</p>

<!-- <br>、<img>、<input>、<hr>などの空要素には閉じタグは不要です -->

---
import Layout from '../layouts/Layout.astro';
---
<Layout>
  <p>ここにコンテンツ

<Layout>
  <p>ここにコンテンツ</p>
</Layout>

アップグレード後にレンダリングされるHTMLの出力が変わった場合は、従来のコンパイラが暗黙的に修正していた無効なHTMLのネストがないか、テンプレートを確認してください。たとえば、<div>を<p>の内側に配置するのは無効なHTMLです。従来のコンパイラはこれを再構成してくれましたが、Rustコンパイラはそうしません:

<!-- 無効なネスト: <div>は<p>の内側では許可されていません -->
<!-- ブラウザは<p>を早めに閉じるため、レイアウトが崩れる可能性があります -->
<p>
  <div>これは段落の内側には入りません</div>
</p>

<!-- 修正: 代わりに有効なコンテナを使用します -->
<div>
  <div>これは正しくネストされています</div>
</div>

CSS出力の違い

Rustコンパイラは、CSSを異なる方法で処理します。これにより、ビルドされた出力に軽微な見た目の違いが生じる場合があります。

色の値のシリアライズ方法が異なる場合があります。 rebeccapurpleのような名前付きの色が、ビルドされたCSSでは#639のような16進数値になることがあります。これによってサイトの見た目が変わることはありません。
url()の値で引用符が追加または削除される場合があります。 たとえば、url(/path)がurl('/path')になったり、その逆になったりすることがあります。これによって機能に影響はありません。

これらの違いは見た目上のものであり、CSS文字列の完全一致に依存するテストやツールを使用していない限り、対応は不要です。

予約済みのファイル名: `src/fetch.ts`

Astro v7.0では高度なルーティング (EN)が導入され、src/middleware.tsと同様に、src/fetch.ts（またはsrc/fetch.js）が特別なファイル名として使用されるようになりました。Astroはこのファイルを自動的にインポートし、ルーティングの動作を設定します。

プロジェクトに別の目的で使用しているsrc/fetch.tsファイルがすでに存在する場合、Astroはそれを高度なルーティングの設定として処理しようとし、予期しないエラーが発生する可能性があります。

どうすればよいですか？

高度なルーティングとは無関係な既存のsrc/fetch.tsファイルがある場合は、2つの選択肢があります。

fetchFileを設定する: 別のファイル名を指定するか、nullを指定して高度なルーティングを無効にできます。これは、src/fetch.tsを別の目的で引き続き使用したい場合や、高度なルーティング機能が不要な場合に便利です。
astro.config.mjs
```
import { defineConfig } from 'astro/config';

export default defineConfig({
  // 高度なルーティングの設定に別のファイルを指定する:
  fetchFile: './src/router.ts',
  // または高度なルーティングを完全に無効にする:
  // fetchFile: null,
});
```
ファイルをリネームする: 別の名前（例：src/fetcher.ts、src/main.ts）に変更し、それを参照しているインポートをすべて更新してください。

新しいデフォルトのMarkdownプロセッサー: Sätteri

実装PR：feat: make Sätteri the default Markdown pipeline (#16966)

Astroは、.mdおよび.mdxファイルを、remark/rehypeパイプラインの代わりに、ネイティブのMarkdownパイプラインであるSätteriでレンダリングするようになりました。その結果、@astrojs/markdown-remarkはデフォルトではインストールされなくなりました。

どうすればよいですか？

remarkやrehypeのプラグインを使用していない場合は、何もする必要はありません。MarkdownとMDXはSätteriでレンダリングされるようになり、これまでと同様にGitHub Flavored MarkdownとSmartyPantsが適用されます。

remarkやrehypeのプラグインに依存している場合は、それらをSätteriのMDASTまたはHASTプラグインに移植できます。recmaプラグインに依存している場合や、remarkおよびrehypeプラグインを移植する準備がまだ整っていない、または移植できない場合は、unified()パイプラインを使い続けることができます。

unifiedプラグインを引き続き使用するには、以下のようにします。

@astrojs/markdown-remarkをインストールします:
- npm
- pnpm
- Yarn
Terminal window
npm install @astrojs/markdown-remark
Terminal window
pnpm add @astrojs/markdown-remark
Terminal window
yarn add @astrojs/markdown-remark

unified()をMarkdownプロセッサーとして設定します:

import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';

export default defineConfig({
  markdown: {
    processor: unified(),
  },
});

非推奨となったmarkdown.remarkPlugins、markdown.rehypePlugins、markdown.remarkRehypeオプションは引き続き動作しますが、現在は@astrojs/markdown-remarkのインストールも必要になります。

新しいデフォルトの空白処理: `compressHTML: 'jsx'`

実装PR：feat: make jsx whitespace handling the default (#16965)

Astro v6.xでは、空白処理にデフォルトでHTMLを考慮した圧縮が使用されていました。これは、AstroがHTMLのルールに従ってインライン要素間の単一のスペースを保持することを意味します。

Astro v7.0では、compressHTML (EN)のデフォルト値がtrueから'jsx'に変更されました。これにより、AstroはReactのようなフレームワークと同じように、デフォルトでJSXのルールを使用してHTMLから空白を取り除くようになりました。

以下の例は、Astro v6.xではhello worldとレンダリングされていましたが、Astro v7.0ではhelloworldとレンダリングされます。

<span>hello</span>
<em>world</em>

どうすればよいですか？

要素間のスペースが期待どおりにレンダリングされているか、ウェブサイトを目視で確認してください。それ以上の対応は不要な場合もあります。

一部のスペースが失われていることに気づいた場合は、インライン要素を使用しているコンポーネントやページを特定してください。そして、{" "}を使用してこれらの要素間に明示的なスペースを追加するよう更新してください。

<span>hello</span>
<em>world</em>
<span>hello</span> <em>world</em>

以前の動作を維持したい場合は、compressHTMLをtrueに設定してください。また、compressHTML: falseを使用してすべての空白を保持することもできます。

import { defineConfig } from 'astro/config';

export default defineConfig({
  compressHTML: true,
});

非推奨

以下の非推奨機能はサポートされなくなり、ドキュメントにも記載されなくなりました。プロジェクトを適切に更新してください。

一部の非推奨機能は、完全に削除されるまで一時的に動作し続ける場合があります。その他の機能は、何も起こらず無視されるか、コードの更新を促すエラーをスローする場合があります。

非推奨: インテグレーションパッケージのルートからの`getContainerRenderer()`

実装PR：fix(integrations): Export container renderers from a dedicated export path to fix bundling issues (#17093)

Astro 6.xでは、Container APIで使用するgetContainerRenderer() (EN)ヘルパーを、公式インテグレーションのパッケージのルート（例：@astrojs/react）からインポートしていました。これにより、Container APIだけが必要な場合でも、バンドラーがパッケージのルートから無関係なビルド時専用のエクスポートを取り込んでしまう可能性がありました。

Astro 7.0では、インテグレーションのパッケージのルートからgetContainerRenderer()をインポートすることを非推奨とし、代わりに専用のcontainer-rendererエントリーポイントの使用が推奨されます。

どうすればよいですか？

各公式インテグレーションについて、Container APIのインポートを新しいcontainer-rendererエントリーポイントを使用するように更新してください。

import { getContainerRenderer } from '@astrojs/react';
import { getContainerRenderer } from '@astrojs/react/container-renderer';

このエントリーポイントは、@astrojs/react、@astrojs/preact、@astrojs/solid-js、@astrojs/svelte、@astrojs/vue、@astrojs/mdxで利用できます。

削除

以下の機能はコードベースから完全に削除され、使用できなくなりました。一部の機能は非推奨化後もプロジェクト内で動作し続けていた場合があります。また、何も起こらず無視されていた機能もあります。

削除された機能がプロジェクトに残っている場合、ビルドが失敗します。これらの機能の削除を促すドキュメントも今後は提供されません。

削除: `@astrojs/db`

@astrojs/dbパッケージはAstro v7.0で削除され、メンテナンスされなくなりました。

どうすればよいですか？

@astrojs/dbをプロジェクトの依存関係から削除し、以下のいずれかの代替手段に置き換えてください。

Node.js組み込みのSQLite: Node.jsには組み込みのnode:sqliteモジュールが含まれるようになりました（Node.js v22.5.0以降で利用可能）。Node.jsアダプターを使用していて、ローカルのSQLiteストレージのために@astrojs/dbを使用していた場合は、これが適した選択肢です。
Drizzle ORM: @astrojs/dbのDrizzleベースのスキーマおよびクエリAPIのために使用していた場合は、サポートされている任意のデータベースでDrizzleを直接使用できます。
その他のデータベースライブラリ: デプロイ先のプラットフォームに適した任意のデータベースライブラリ（例：Turso、PlanetScale、Neon）を使用してください。

削除: 公開されていた`astro:transitions`の内部API

実装PR：feat: remove deprecated astro:transitions internals (#16725)

Astro 6.xでは、astro:transitionsおよびastro:transitions/clientで利用可能だった一部のヘルパーが非推奨となりました。

Astro 7.0では、以下のAPIをプロジェクト内で使用できなくなりました。

TRANSITION_BEFORE_PREPARATION
TRANSITION_AFTER_PREPARATION
TRANSITION_BEFORE_SWAP
TRANSITION_AFTER_SWAP
TRANSITION_PAGE_LOAD
isTransitionBeforePreparationEvent()
isTransitionBeforeSwapEvent()
createAnimationScope()

どうすればよいですか？

createAnimationScope()の使用箇所をすべて削除してください。

import { createAnimationScope } from 'astro:transitions';

その他のAPIの使用箇所は、ライフサイクルイベント名 (EN)を直接使用するように置き換えてください。

import {
  TRANSITION_AFTER_SWAP,
  isTransitionBeforePreparationEvent,
} from 'astro:transitions/client';

console.log(isTransitionBeforePreparationEvent(event));
console.log(event.type === 'astro:before-preparation');

console.log(TRANSITION_AFTER_SWAP);
console.log('astro:after-swap');

ビュートランジションルーターAPIリファレンス (EN)で、利用可能なすべてのユーティリティを確認してください。

貢献するコミュニティスポンサー

Astro v7へのアップグレード

Astroのアップグレード

破壊的な変更

依存関係のアップグレード

Vite 8

どうすればよいですか？

実験的フラグ

安定版になった実験的機能:

Rustコンパイラ

どうすればよいですか？

CSS出力の違い

予約済みのファイル名: src/fetch.ts

どうすればよいですか？

新しいデフォルトのMarkdownプロセッサー: Sätteri

どうすればよいですか？

新しいデフォルトの空白処理: compressHTML: 'jsx'

どうすればよいですか？

非推奨

非推奨: インテグレーションパッケージのルートからのgetContainerRenderer()

どうすればよいですか？

削除

削除: @astrojs/db

どうすればよいですか？

削除: 公開されていたastro:transitionsの内部API

どうすればよいですか？

予約済みのファイル名: `src/fetch.ts`

新しいデフォルトの空白処理: `compressHTML: 'jsx'`

非推奨: インテグレーションパッケージのルートからの`getContainerRenderer()`

削除: `@astrojs/db`

削除: 公開されていた`astro:transitions`の内部API