Astro v6へのアップグレード

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

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

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

Astroのアップグレード

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

npm

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

pnpm

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

Yarn

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

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

これで終わりですか？

Astroをアップグレードした後、プロジェクトに変更を加える必要がまったくない場合もあります！

ただし、エラーや予期しない動作に気づいた場合は、以下を読んでプロジェクトの更新が必要な変更点がないか確認してください。

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

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

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

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

Astroの依存関係のメジャーアップグレードにより、プロジェクトに破壊的な変更が生じる場合があります。

Node 22

実装PR：feat!: drop node 18 and 20 (#14427)

Node 18は2025年3月にサポート終了を迎えました。またNode 20は2026年4月にサポート終了を迎える予定です。

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

どうすればよいですか？

開発環境と本番環境の両方でNode 22.12.0以上を使用していることを確認してください。

1. ローカルのNodeバージョンを以下のコマンドで確認します。

   node -v

2. 本番環境 (EN)のドキュメントを確認し、Node 22がサポートされていることを確認します。

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

   .nvmrc

   22.12.0

Vite 7.0

実装PR：feat: update vite (#14445)

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

どうすればよいですか？

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

AstroのgetViteConfig()ヘルパーを使用するには、Vitest v3.2またはv4.1 beta 5以上が必要です。

Vite Environment API

実装PR：feat: integrate vite environments (#14306)

Astro v6.0では、ViteのEnvironments APIを使用するための内部リファクタリングにともない、Astroが異なるランタイム環境（クライアント、サーバー、プリレンダリング）を管理する方法に大きな変更が加えられました。

どうすればよいですか？

インテグレーションやアダプターのメンテナは、インテグレーションAPIおよびアダプターAPIの以下の部分に影響する変更に特に注意してください（詳細については、これらのAPIへの他の破壊的な変更とともに後述しています）。

• Rollup出力ファイル名の設定パス
• インテグレーションフックとHMRアクセスパターン
• SSRManifestの構造
• RouteDataによるルート生成
• パーセントエンコードされたパーセント記号を含むルート（例：%25）
• astro:ssr-manifest仮想モジュール
• astro/app/nodeのNodeApp
• astro/app/nodeのloadManifest()とloadApp()
• createExports()とstart()

Zod 4

Astro v6.0ではZodがv4にアップグレードされました。この依存関係のメジャーバージョンの更新により、プロジェクト内のカスタムZodスキーマに変更が必要になる場合があります。

どうすればよいですか？

content.config.tsやその他の設定ファイルでカスタムZodスキーマを使用している場合は、Zod 4に合わせて更新する必要があります。Zod APIの変更点の詳細については、Zodの移行ガイドを参照してください。

特に注目すべき点として、多くのstring()フォーマットが非推奨になり（例：z.string().email()、z.string.url()）、それらのAPIはトップレベルのz名前空間に移動されました。以下のようにAstro Actionsでフォーム入力を検証する方法の更新が必要になる場合があります。

src/actions/index.ts

email: z.string().email(),
email: z.email(),

また、Zodではエラーメッセージの処理にいくつかの変更が加えられ、エラーメッセージの再定義や翻訳に便利だったカスタムerrorsMapのサポートが廃止されました。以下のようにカスタムエラーメッセージの更新が必要になる場合があります。

src/actions/index.ts

z.string().min(5, { message: "Too short." });
z.string().min(5, { error: "Too short." });

さらに、.default()をtransformと組み合わせて使用している場合は、スキーマの更新が必要になることがあります。Zod 4では、デフォルト値は入力の型ではなく出力の型（transform適用後）と一致する必要があります。入力がundefinedの場合、デフォルト値によりパースがショートサーキットされます。

src/content.config.ts

import { z } from 'astro/zod';

const blog = defineCollection({
  schema: z.object({
    // Zod 3: デフォルト値は入力の型（string）と一致
    views: z.string().transform(Number).default("0"),
    // Zod 4: デフォルト値は出力の型（number）と一致する必要がある
    views: z.string().transform(Number).default(0),
  })
});

デフォルト値がパースされる以前の動作が必要な場合は、新しい.prefault()メソッドを使用してください。

これらはZod 3からZod 4へのアップグレードにともなう多くの変更の一部にすぎません。Astro 6へのアップグレード後にZodスキーマで問題が発生した場合は、Zod 4のchangelogで完全なアップグレードガイダンスを確認してください。

また、Zod 3からZod 4への移行時に、これらの変更の一部を自動化できる可能性があるコミュニティ製のcodemodも利用可能です。

astro/zodからZodをインポートすることで、Astroが内部で使用しているものと同じバージョンのZodを使用できます。

import { z } from 'astro/zod';

astro/zodモジュール (EN)の詳細を確認してください。

Shiki 4.0

実装PR：chore(deps): update shiki to v4 (#15726)

Astro v6.0では、シンタックスハイライトに使用するShikiがv4.0にアップグレードされました。

どうすればよいですか？

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

Astro公式インテグレーション

ViteのEnvironment APIを開発サーバーおよびプロダクションバンドラーとして使用するVite v7.0へのアップグレードにともない、Astroの公式サーバーアダプターもすべて新しいメジャーバージョンに更新されました。

特にAstroのCloudflareアダプターには大幅な変更が加えられており、既存のCloudflareの設定に破壊的な変更が生じることが想定されます。

詳細な移行手順については、Cloudflareアダプターのアップグレード手順 (EN)を確認してください。

どうすればよいですか？

オンデマンドレンダリングやその他のプラットフォーム固有の機能のためにAstroアダプターを使用している場合は、各アダプターのchangelogでアップグレードの手順を確認してください。

• @astrojs/cloudflare CHANGELOG
• @astrojs/netlify CHANGELOG
• @astrojs/node CHANGELOG
• @astrojs/vercel CHANGELOG

レガシー

以下の機能はレガシーな機能とみなされるようになりました。通常通り動作しますが、使用は推奨されずメンテナンスモードに移行しています。今後の改善はおこなわれず、ドキュメントも更新されません。これらの機能はいずれ非推奨となり、最終的には完全に削除されます。

レガシー: コンテンツコレクションの後方互換性

Astro 5.xでは、コンテンツコレクション向けに導入された新しいContent Layer APIへのアップグレードを先延ばしにできました。これは、フラグを有効にしなくても自動的に適用される後方互換性が存在していたためです。つまり、legacy.collectionsフラグを有効にしていなくても、コンテンツコレクションを更新せずにAstro 4からAstro 5にアップグレードできました。プロジェクトは引き続きビルドでき、エラーや警告は表示されませんでした。

Astro v6.0では、この自動的なレガシーコンテンツコレクションのサポートが、legacy.collectionsフラグとともに削除されました。すべてのコンテンツコレクションは、Astro v5.0で導入されたコンテンツレイヤーAPIを使用する必要があります。

どうすればよいですか？

v6への更新後にコンテンツコレクションのエラーが発生した場合は、コンテンツレイヤーAPIへの更新が必要な削除されたレガシー機能がプロジェクトにないか確認してください。

レガシーコレクションを新しいコンテンツレイヤーAPIにアップグレードする詳細な手順については、Astro v5アップグレードガイド (EN)を確認してください。

すぐに更新できない場合は、一時的な移行ヘルパーとしてlegacy.collectionsBackwardsCompatフラグ (EN)を有効にできます。

astro.config.mjs

export default defineConfig({
  legacy: {
    collectionsBackwardsCompat: true,
  },
});

このフラグにより、レガシーなv4のコンテンツコレクションの一部機能が維持されます。

• レガシーな設定ファイルsrc/content/config.tsのサポート
• ローダーなしのtype: 'content'とtype: 'data'のサポート
• レガシーエントリーAPI（entry.slugとentry.render()）の維持
• スラッグではなくパスを基準としたエントリーIDの使用

これは一時的な移行ヘルパーです。 できるだけ早くコレクションをコンテンツレイヤーAPIに移行し、このフラグを無効にしてください。

非推奨

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

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

非推奨: getStaticPaths()内のAstro

実装PR：feat: deprecate Astro in getStaticPaths (#14432)

Astro 5.xでは、getStaticPaths()内でAstroオブジェクトにアクセスできました。しかし、フロントマターでアクセス可能なAstroオブジェクトと同じ型が付けられているにもかかわらず、このオブジェクトにはsiteとgeneratorプロパティしかありませんでした。これにより、getStaticPaths()内で利用可能なAstroオブジェクトのプロパティについて混乱が生じる可能性がありました。

Astro 6.0では、混乱を避けるためにgetStaticPaths()内でのこのオブジェクトの使用を非推奨とし、利用できないAstroの値にアクセスしようとした際のエラー処理を改善しました。getStaticPaths()内でAstro.siteやAstro.generatorを使用すると非推奨の警告がログに出力されるようになり、それ以外のプロパティにアクセスするとわかりやすいメッセージとともにエラーがスローされます。将来のメジャーバージョンでは、このオブジェクトは完全に削除され、Astro.siteやAstro.generatorへのアクセスもエラーをスローするようになります。

どうすればよいですか？

getStaticPaths()のスコープ内でAstroのプロパティにアクセスしていた場合は、関数を更新してください。Astro.generatorは完全に削除し、Astro.siteはすべてimport.meta.env.SITEに置き換えます。

src/pages/blog/[slug].astro

---
import { getPages } from "../../../utils/data";

export async function getStaticPaths() {
  console.log(Astro.generator);
  return getPages(Astro.site);
  return getPages(import.meta.env.SITE);
}
---

getStaticPaths()を使用して静的ルートを動的に生成する (EN)際にアクセスできるimport.meta.env.SITEなどの組み込み環境変数 (EN)の詳細を確認してください。

非推奨: import.meta.env.ASSETS_PREFIX

実装PR：feat: deprecate import.meta.env.ASSETS_PREFIX (#14461)

Astro 5.xでは、組み込みの環境変数import.meta.env.ASSETS_PREFIXを通じてAstro設定のbuild.assetsPrefixにアクセスできました。しかし、Astro v5.7.0でastro:config仮想モジュールが導入され、Astro設定の一部を型安全かつシリアライズ可能なかたちで公開できるようになりました。これによりbuild.assetsPrefixにも直接アクセスできるようになり、アセットリンクのプレフィックスを取得する方法としてはこちらが推奨されるようになりましたが、環境変数自体は引き続き利用可能でした。

Astro 6.0ではこの変数を非推奨とし、代わりにastro:config/serverモジュールのbuild.assetsPrefixの使用を推奨します。

どうすればよいですか？

import.meta.env.ASSETS_PREFIXのすべての箇所を、astro:config/serverからのbuild.assetsPrefixインポートに置き換えてください。これは既存の値をそのまま提供するドロップイン置換であり、コードにその他の変更を加える必要はありません。

import { someLogic } from "./utils"
import { build } from "astro:config/server"

someLogic(import.meta.env.ASSETS_PREFIX)
someLogic(build.assetsPrefix)

astro:config仮想モジュール (EN)の詳細を確認してください。

非推奨: astro:schemaおよびastro:contentのz

実装PR：feat!: consolidate zod export (#14923)

Astro 5.xでは、astro:schemaがastro/zodのエイリアスとして導入されました。また、利便性のためにastro:contentからもzがエクスポートされていました。しかし、どこからインポートすべきかわかりにくいという混乱を招くことがありました。

Astro 6.0では、astro:schemaおよびastro:contentのzを非推奨とし、代わりにastro/zodの使用を推奨します。

どうすればよいですか？

astro:schemaをすべてastro/zodに置き換えてください。

import { z } from "astro:schema"
import { z } from "astro/zod"

astro:contentのインポートからzを削除し、代わりにastro/zodから別途インポートしてください。

src/content.config.ts

import { defineCollection, z } from "astro:content"
import { defineCollection } from "astro:content"
import { z } from "astro/zod"

Zodを使用したコレクションスキーマの定義 (EN)の詳細を確認してください。

非推奨: astro:transitionsの内部API

実装PR：feat!: deprecate transitions exports (#14989)

Astro 5.xでは、astro:transitionsおよびastro:transitions/clientから、本来公開を意図していない内部APIがエクスポートされていました。

Astro 6.0では、astro:transitionsおよびastro:transitions/client仮想モジュールから以下の関数・型のエクスポートを削除しました。これらはプロジェクトファイル内でインポートできなくなります。

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

どうすればよいですか？

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

import { createAnimationScope } from 'astro:transitions';

その他の非推奨エクスポートは以下のように更新してください。

import {
  isTransitionBeforePreparationEvent,
  TRANSITION_AFTER_SWAP,
} 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)で利用可能なすべてのユーティリティを確認してください。

非推奨: セッションドライバーの文字列指定

実装PR：feat(sessions): drivers (#15006)

Astro 5.xでは、セッションドライバーの定義にunstorageプロバイダーの名前やカスタムエントリーポイントを指定でき、オプションもsession設定に直接渡していました。しかし、このAPIには制約があり、Astro設定の他の部分との一貫性にも欠けていました。

Astro 6.0では、ドライバーの文字列指定とオプションを非推奨とし、新しいオブジェクト形式を導入しました。

どうすればよいですか？

セッション設定を、新しくエクスポートされたsessionDriversを使用するかたちに更新してください。

astro.config.mjs

import { defineConfig } from 'astro/config'
import { defineConfig, sessionDrivers } from 'astro/config'

export default defineConfig({
  session: {
    driver: 'redis',
    options: {
      url: process.env.REDIS_URL
    },
    driver: sessionDrivers.redis({
      url: process.env.REDIS_URL
    }),
    cookie: {
      secure: true
    },
    ttl: 3600
  }
})

利用可能なセッションドライバー (EN)の詳細を確認してください。

非推奨: astro/app/nodeのNodeApp（アダプターAPI）

実装PR：feat: deprecate NodeApp (#15535)

Astro 5.xでは、アダプターのサーバーエントリーポイントを、標準のWebリクエスト/レスポンス用のApp、またはNodeリクエスト/レスポンス用のNodeAppを使って実装できました。

Astro 6.0では、NodeAppを非推奨とし、代わりにcreateApp()と新しいユーティリティcreateRequest()およびwriteResponse()を導入しました。これにより、従来と同じ機能を維持しつつ、より一貫性のあるAPIになります。NodeAppHeadersJson型も同様に非推奨となりました。

どうすればよいですか？

アダプターを作成している場合は、NodeAppの使用箇所をcreateApp()に更新してください。

my-adapter/server.js

import { NodeApp } from 'astro/app/node';

export function createExports(manifest) {
  const app = new NodeApp(manifest);

  const handler = async (req, res) => {
    const response = await app.render(req);
    await NodeApp.writeResponse(response, res);
  };

  return { handler };
}
import { createApp } from 'astro/app/entrypoint';
import { createRequest, writeResponse } from 'astro/app/node';

const app = createApp();

export const handler = async (req, res) => {
  const request = createRequest(req);
  const response = await app.render(request);
  await writeResponse(response, res);
}

astro/app/nodeモジュール (EN)の詳細を確認してください。

非推奨: astro/app/nodeのloadManifest()とloadApp()（アダプターAPI）

実装PR：feat: deprecate NodeApp (#15535)

Astro 5.xでは、astro/app/nodeからloadManifest()とloadApp()ユーティリティが公開されており、URLインスタンスからSSRマニフェストやNodeAppインスタンスを読み込めました。ただし、これらはドキュメントに記載されておらず、v6のアダプターAPIでは推奨されなくなりました。

Astro 6.0では、これら両方の関数を非推奨としました。

どうすればよいですか？

アダプターを作成している場合は、loadManifest()を削除し、loadApp()をcreateApp()に置き換えてください。

my-adapter/server.js

import { loadManifest, loadApp, NodeApp } from 'astro/app/node';

const manifest = await loadManifest(new URL(import.meta.url));
const app1 = new NodeApp(loadManifest);
const app2 = await loadApp(new URL(import.meta.url));
import { createApp } from 'astro/app/entrypoint';

const app = createApp();

astro/app/entrypointモジュール (EN)の詳細を確認してください。

非推奨: createExports()とstart()（アダプターAPI）

実装PR：feat: improve naming of new adapter api (#15461)

Astro 5.xでは、アダプターはサーバーエントリーポイントでcreateExports()関数を使用してホストが必要とするエクスポートを提供し、それをsetAdapter()にexportsリストとして渡す必要がありました。

Astro 6.0では、サーバーエントリーポイントをよりシンプルかつ柔軟に作成できる方法を導入しました。setAdapter()に新しいオプションentrypointResolution: "auto"を渡すことで利用できます。

ただし、既存のアダプターとの後方互換性のため、entrypointResolutionのデフォルト値（"explicit"）はAstro 5.xのAPIの挙動を維持しています。そのため、以下に示すautoへの完全な移行が完了するまで、アダプターは引き続き動作します。

なお、entrypointResolution: "explicit"（v5のAPI動作を維持）は非推奨とみなされますが、アダプターへの即座の変更が不要になるよう、またアダプター作者が更新するための猶予期間として提供されています。このオプションは将来のメジャーバージョンで削除され、すべてのアダプターがentrypointResolution: "auto"を使用することになります。

どうすればよいですか？

あなたが公開リポジトリをもつアダプターの作者で、package.jsonにastro-adapterキーワードを含めている場合、以下の手順がまだ実施されていなければ、Astroコアチームがコードの移行を支援するPRをリポジトリに直接作成することがあります。

まだ更新されていないコミュニティアダプターを使用していて警告が表示される場合は、アダプターの作者に直接連絡してください。アダプターの更新は最終的には作者の責任です。また、Discordの#integrationsチャンネルでAstroコアチームに知らせてもらえれば、私たちがアダプター作者のアップグレードを支援します。

あなたがアダプターの作者である場合は、以下の手順でレガシーなv5の動作を削除してください。

1. setAdapter()を更新します。entrypointResolution: "auto"を設定し、exportsとargsを削除してください。

   my-adapter.mjs

   setAdapter({
     // ...
     entrypointResolution: 'auto',
     exports: ['handler'],
     args: { assets: config.build.assets }
   })

2. サーバーエントリーポイントを更新し、createExports()を使わずに必要なエクスポートを提供するようにします。

   my-adapter/server.js

   import { App } from 'astro/app';
   
   export function createExports(manifest) {
     const app = new App(manifest);
   
     const handler = (event, context) => {
       // ...
     };
   
     return { handler };
   }
   import { createApp } from 'astro/app/entrypoint';
   
   const app = createApp();
   
   export const handler = (event, context) => {
     // ...
   }

3. アダプターがstart()関数を提供している場合は、サーバーエントリーポイントでコードを直接呼び出すように更新します。

   my-adapter/server.js

   import { App } from 'astro/app';
   
   export function start(manifest) {
     const app = new App(manifest);
   
     addEventListener('fetch', event => {
       // ...
     });
   }
   import { createApp } from 'astro/app/entrypoint';
   
   const app = createApp();
   
   addEventListener('fetch', event => {
     // ...
   });

4. argsを使用していた場合は、仮想モジュールを作成してビルド時の設定を渡し (EN)、その仮想モジュールからインポートするようにしてください。

   my-adapter/server.js

   export function createExports(manifest, { assets }) {
     // ...
   }
   import { assets } from 'virtual:@example/my-adapter:config';

アダプターAPI (EN)の詳細を確認してください。

削除

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

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

削除: レガシーコンテンツコレクション

実装PR：fix: remove legacy content collections (#14407)

Astro 5.xでは、legacy設定フラグまたは組み込みの後方互換性のいずれかを通じて、Astro v2.0で最初に導入されたオリジナルのコンテンツコレクションAPIを引き続き使用できました。これらの方法により、既存のコンテンツコレクションを新しいコンテンツレイヤーAPIに対応する準備ができていない場合でも、Astro v5にアップグレードできました。

Astro v6.0では、この非推奨のコンテンツコレクションAPIサポートが完全に削除されました。legacy.collectionsフラグに加え、フラグを有効にしなくても自動的に適用されていた後方互換性も含めてすべて削除されています。すべてのコンテンツコレクションは、Astro v5.0で導入されたコンテンツレイヤーAPIを使用する必要があります。後方互換性のサポートは利用できません。

どうすればよいですか？

以前にレガシーフラグを有効にしていた場合は、削除する必要があります。

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  legacy: {
    collections: true,
  }
})

さらに、Astro v5.0の時点でコレクションをアップグレードしていなかった場合は、コンテンツコレクションが新しいAPIに完全に対応していることを確認してください。

Astro v5.xには、新しいAPIに更新されていなくてもコンテンツコレクションが動作し続けるための自動的な後方互換性が含まれていました。そのため、以前はプロジェクトにエラーがなかったとしても、v5のコレクションにはv6に向けて更新が必要なレガシー機能が含まれている可能性があります。

v6へのアップグレード後にコンテンツコレクションのエラー (EN)や警告が発生した場合は、以下のリストを参考にして、コード内に残っているレガシー機能を特定し、アップグレードしてください。

確認が必要な項目

コンテンツコレクションの設定ファイルがない

src/content.config.tsを作成し、その中でコレクションを定義 (EN)してください。

設定ファイルがsrc/content/config.tsにある（LegacyContentConfigError (EN)）

このファイルをsrc/content.config.tsにリネームして移動してください。

loaderが定義されていないコレクション（ContentCollectionMissingALoaderError (EN)）

Astro組み込みのglob()ローダー (EN)をインポートし、コレクションエントリーのpatternとbaseを定義してください。

src/content.config.ts

import { defineCollection } from 'astro:content';
import { z } from 'astro/zod';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: "./src/data/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
  }),
});

コレクションタイプ（type: 'content'またはtype: 'data'）を定義しているコレクション（ContentCollectionInvalidTypeError (EN)）

コレクションのタイプの区別はなくなりました。コレクション定義からこれを削除する必要があります。

src/content.config.ts

import { defineCollection } from 'astro:content';
import { z } from 'astro/zod';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  // コンテンツレイヤーでは`type`の定義は不要です
  type: 'content',
  loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: "./src/data/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
  }),
});

レガシーなコレクションクエリメソッドgetDataEntryById()およびgetEntryBySlug()を使用している（GetEntryDeprecationError (EN)）

両方のメソッドをgetEntry() (EN)に置き換えてください。

slugプロパティに依存するレガシーなコレクションのクエリレンダリングメソッドを使用している（ContentSchemaContainsSlugError (EN)）

以前はidがファイル名に基づいており、URLに使用できるslugプロパティがありました。現在はCollectionEntry (EN)のidがスラッグになっています。ファイル名（以前はidとして利用可能だったもの）にアクセスする必要がある場合は、filePathプロパティを使用してください。slugのすべての箇所をidに置き換えます。

src/pages/[slug].astro

---
export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map((post) => ({
    params: { slug: post.slug },
    params: { slug: post.id },
    props: post,
  }));
}
---

entry.render()を使用してコンテンツをレンダリングしている

コレクションエントリーにはrender()メソッドがなくなりました。代わりに、astro:contentからrender()関数をインポートし、render(entry)を使用してください。

src/pages/index.astro

---
import { getEntry, render } from 'astro:content';

const post = await getEntry('pages', 'homepage');

const { Content, headings } = await post.render();
const { Content, headings } = await render(post);
---
<Content />

Astro v5でのレガシーコレクションの後方互換性に関する以前のガイダンスと、レガシーコレクションを新しいコンテンツレイヤーAPIにアップグレードするための詳細な手順については、Astro v5アップグレードガイド (EN)を確認してください。

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

実装PR：Remove deprecated ViewTransitions component (#14400)

Astro 5.0では、コンポーネントの役割を明確にするために<ViewTransitions />が<ClientRouter />にリネームされました。新しい名前により、Astroの<ClientRouter />ルーティングコンポーネントが提供する機能が、ネイティブのCSSベースのMPAルーターとは若干異なることがより明確になりました。ただし、非推奨化された<ViewTransitions />コンポーネントはAstro 5.xでも引き続き存在し、動作する場合がありました。

Astro 6.0では<ViewTransitions />コンポーネントが完全に削除され、プロジェクト内で使用できなくなりました。これらの機能を引き続き使用するには、<ClientRouter />コンポーネントに更新してください。

どうすればよいですか？

ViewTransitionsのインポートとコンポーネントをすべてClientRouterに置き換えてください。

src/layouts/MyLayout.astro

import { ViewTransitions } from 'astro:transitions';
import { ClientRouter } from 'astro:transitions';

<html>
  <head>
    ...
    <ViewTransitions />
    <ClientRouter />
  </head>
</html>

Astroのビュートランジションとクライアントサイドルーティング (EN)の詳細を確認してください。

削除: emitESMImage()

実装PR：feat!: remove emitESMImage() (#14426)

Astro 5.6.2では、emitESMImage()関数が非推奨となり、公開を意図していなかった2つの引数（_watchModeとexperimentalSvgEnabled）を削除したemitImageMetadata()が後継として導入されました。

Astro 6.0ではemitESMImage()が完全に削除されました。現在の動作を維持するには、emitImageMetadata()に更新してください。

どうすればよいですか？

emitESMImage()をすべてemitImageMetadata()に置き換え、不要な引数を削除してください。

import { emitESMImage } from 'astro/assets/utils';
import { emitImageMetadata } from 'astro/assets/utils';

const imageId = '/images/photo.jpg';
const result = await emitESMImage(imageId, false, false);
const result = await emitImageMetadata(imageId);

emitImageMetadata() (EN)の詳細を確認してください。

削除: Astro.glob()

実装PR：feat!: remove Astro.glob (#14421)

Astro 5.0では、コレクションのクエリにはgetCollection()を、プロジェクト内のその他のソースファイルのクエリにはimport.meta.glob()を使用することが推奨され、Astro.glob()は非推奨となりました。

Astro 6.0ではAstro.glob()が完全に削除されました。現在の動作を維持するには、import.meta.glob()に更新してください。

どうすればよいですか？

Astro.glob()の使用箇所をすべてimport.meta.glob()に置き換えてください。import.meta.glob()はPromiseを返さなくなったため、それに応じてコードの更新が必要になる場合があります。globパターン (EN)の変更は不要です。

src/pages/blog.astro

---
const posts = await Astro.glob('./posts/*.md');
const posts = Object.values(import.meta.glob('./posts/*.md', { eager: true }));
---

{posts.map((post) => <li><a href={post.url}>{post.frontmatter.title}</a></li>)}

必要に応じて、コンテンツの整理にコンテンツコレクション (EN)の使用を検討してください。コンテンツコレクションには、より新しく高パフォーマンスなクエリ関数が用意されています。

また、fast-globなどのNPMのglobパッケージの使用も検討可能です。

import.meta.globによるファイルのインポート (EN)の詳細を確認してください。

削除: astro:actionsの内部API

実装PR：refactor: cleanup public actions API (#14844)

Astro 5.xでは、astro:actionsから本来公開を意図していない内部APIがエクスポートされていました。

Astro 6.0では、astro:actions仮想モジュールから以下の関数、クラス、型のエクスポートが削除されました。これらはプロジェクトファイル内でインポートできなくなります。

• ACTION_ERROR_CODES
• ActionInputError
• appendForwardSlash
• astroCalledServerError
• callSafely
• deserializeActionResult
• formDataToObject
• getActionQueryString
• serializeActionResult
• type Actions
• type ActionAccept
• type AstroActionContext
• type SerializedActionResult

どうすればよいですか？

serializeActionResult()とdeserializeActionResult()のインポートをすべてgetActionContext()に置き換えてください。これら2つのメソッドはgetActionContext()を通じて利用できるようになりました。

src/middleware.ts

import { defineMiddleware } from 'astro:middleware';
import { serializeActionResult, deserializeActionResult } from 'astro:actions';
import { getActionContext } from 'astro:actions';

export const onRequest = defineMiddleware(async (context, next) => {
  const { serializeActionResult, deserializeActionResult } = getActionContext(context);
  // ...
});

その他の削除されたエクスポートの使用箇所をすべて削除してください。

import {
  ACTION_ERROR_CODES,
  ActionInputError,
  appendForwardSlash,
  astroCalledServerError,
  callSafely,
  formDataToObject,
  getActionQueryString,
  type Actions,
  type ActionAccept,
  type AstroActionContext,
  type SerializedActionResult,
} from 'astro:actions';

アクションAPIリファレンス (EN)で利用可能なすべてのユーティリティを確認してください。

削除: ルート内のパーセントエンコーディング

実装PR：feat: integrate vite environments (#14306)

Astro 5.xでは、ファイル名にパーセントエンコードされたパーセント記号（%25）を含めることができました。

Astro 6.0では、セキュリティ上の理由からファイル名での%25のサポートが削除されました。この制限により、%25が%にデコードされることで曖昧または無効なエンコーディングシーケンスにつながる可能性のある、エンコーディングベースのセキュリティバイパスを防止します。

どうすればよいですか？

ファイル名に%25を含むルートファイルがある場合は、別の文字を使用するようにリネームしてください。

src/pages/test%25file.astro
src/pages/test-file.astro

削除: astro:ssr-manifest仮想モジュール（インテグレーションAPI）

実装PR：feat: integrate vite environments (#14306)

Astro 5.xでは、非推奨のastro:ssr-manifest仮想モジュールを引き続き使用して設定値にアクセスできました。

Astro 6.0ではastro:ssr-manifest仮想モジュールが完全に削除されました。インテグレーションやAstro内部で使用されなくなっています。マニフェストは仮想モジュールではなく、インテグレーションフックやアダプターAPIを通じて直接渡されるようになりました。ビルド固有のマニフェストデータについては、マニフェストをパラメータとして受け取るastro:build:ssrインテグレーションフックを使用してください。

どうすればよいですか？

インテグレーションやコードがastro:ssr-manifestからインポートしている場合は、代わりにastro:config/serverを使用して設定値にアクセスしてください。

import { manifest } from 'astro:ssr-manifest';
import { srcDir, outDir, root } from 'astro:config/server';
// srcDir、outDir、rootなどを使用して設定値にアクセス

astro:config仮想モジュール (EN)の詳細を確認してください。

削除: RouteData.generate()（アダプターAPI）

実装PR：feat: integrate vite environments (#14306)

Astro 5.xでは、RouteDataのgenerate()メソッドを使用してルートを生成できました。

Astro 6.0では、ルート生成がAstro内部で処理されるようになったため、RouteData.generate()が削除されました。

どうすればよいですか？

コード内のroute.generate()の呼び出しをすべて削除してください。このメソッドは不要になりました。

const generated = route.generate(params);

アダプターAPI (EN)の詳細を確認してください。

削除: astro:build:doneフックのroutes（インテグレーションAPI）

実装PR：feat: cleanup integration api (#14446)

Astro 5.0では、astro:build:doneフックでのroutesへのアクセスが非推奨となりました。

Astro 6.0では、このフックに渡されるroutes配列が完全に削除されました。代わりにastro:routes:resolvedフックを使用してください。

どうすればよいですか？

astro:build:doneに渡されるroutesの使用箇所をすべて削除し、新しいastro:routes:resolvedフックに置き換えてください。新たに公開されたassetsマップからdistURLにアクセスします。

my-integration.mjs

const integration = () => {
    let routes
    return {
        name: 'my-integration',
        hooks: {
            'astro:routes:resolved': (params) => {
                routes = params.routes
            },
            'astro:build:done': ({
                routes
                assets
            }) => {
                for (const route of routes) {
                    const distURL = assets.get(route.pattern)
                    if (distURL) {
                        Object.assign(route, { distURL })
                    }
                }
                console.log(routes)
            }
        }
    }
}

インテグレーション作成のためのインテグレーションAPI astro:routes:resolvedフック (EN)の詳細を確認してください。

削除: astro:build:ssrフックのentryPoints（インテグレーションAPI）

実装PR：feat: cleanup integration api (#14446)

Astro 5.0では、functionPerRouteが非推奨 (EN)となりました。これにより、astro:build:ssrフックのentryPointsは常に空になっていました。

Astro 6.0では、このフックに渡されるentryPointsマップが完全に削除されました。

どうすればよいですか？

astro:build:ssrに渡されるentryPointsの使用箇所をすべて削除してください。

my-integration.mjs

const integration = () => {
    return {
        name: 'my-integration',
        hooks: {
            'astro:build:ssr': (params) => {
                someLogic(params.entryPoints)
            },
        }
    }
}

削除: 古いapp.render()のシグネチャ（アダプターAPI）

実装PR：feat: clean deprecated APIs (#14462)

Astro 4.0では、routeDataとlocalsをオプション引数として個別に渡すapp.render()のシグネチャが非推奨となり、単一のオプション引数renderOptionsを使用する方式が推奨されるようになりました。

Astro 6.0ではこのシグネチャが完全に削除されました。これらの引数を個別に渡そうとすると、プロジェクトでエラーが発生します。

どうすればよいですか？

app.renderの呼び出しを確認し、routeDataとlocalsを複数の独立した引数としてではなく、オブジェクトのプロパティとして渡すようにしてください。

my-adapter/entrypoint.ts

app.render(request, routeData, locals)
app.render(request, { routeData, locals })

アダプターAPI (EN)の詳細を確認してください。

削除: app.setManifestData()（アダプターAPI）

実装PR：chore(astro)!: remove app.setManifestData() (#14758)

Astro 5.0では、app.setManifestData()メソッドがAppとNodeAppで利用可能でしたが、使用されておらず不要なものでした。

Astro 6.0ではこのメソッドが完全に削除されました。

どうすればよいですか？

app.setManifestData()の呼び出しをすべて削除してください。マニフェストを更新する必要がある場合は、新しいAppインスタンスを作成してください。

アダプターAPI (EN)の詳細を確認してください。

削除: <ClientRouter />コンポーネントのhandleFormsプロパティ

実装PR：feat: clean deprecated APIs (#14462)

Astro 4.0では、form要素のsubmitイベントの処理を明示的に有効にする必要がなくなったため、<ClientRouter />コンポーネントのhandleFormsプロパティが非推奨となりました。この機能はデフォルトで組み込まれており、プロジェクトにこのプロパティが残っていても、フォーム送信に影響を与えず無視されていました。

Astro 6.0ではこのプロパティが完全に削除されました。プロジェクトでエラーが発生することを避けるために削除する必要があります。

どうすればよいですか？

<ClientRouter />コンポーネントにhandleFormsプロパティがある場合は削除してください。このプロパティは追加の機能を提供していなかったため、削除してもプロジェクトの動作は変わりません。

src/pages/index.astro

---
import { ClientRouter } from "astro:transitions";
---
<html>
  <head>
    <ClientRouter handleForms />
  </head>
  <body>
    <!-- stuff here -->
  </body>
</html>

フォームでのトランジション (EN)の詳細を確認してください。

削除: prefetch()のwithオプション

実装PR：feat: clean deprecated APIs (#14462)

Astro 4.8.4では、prefetch()関数のwithオプションが非推奨となりました。ページごとにプリフェッチの優先度を指定しなくても適切に動作するデフォルトの挙動が導入されたためです。

Astro 6.0ではこのオプションが完全に削除され、withオプションによるプリフェッチの優先度の設定はできなくなりました。設定しようとするとエラーが発生します。

デフォルトでは、Astroのプリフェッチは自動的なアプローチを使用し、サポートされている場合は常に<link rel="prefetch">を使用し、サポートされていない場合はfetch()にフォールバックします。

どうすればよいですか？

prefetch()の呼び出しを確認し、withオプションが残っている場合は削除してください。

prefetch('/about', { with: 'fetch' });
prefetch('/about');

プリフェッチ (EN)の詳細を確認してください。

削除: アクションコンテキストのrewrite()

実装PR：feat!: remove rewrite from action context (#14477)

Astro 5.5.6では、リライトの代わりにカスタムエンドポイントを使用すべきであるため、ActionAPIContext.rewriteメソッドが非推奨となりました。

Astro 6.0ではActionAPIContextからrewrite()メソッドが完全に削除され、使用できなくなりました。

どうすればよいですか？

アクションのハンドラーを確認し、rewrite()の呼び出しをすべて削除してください。

src/actions/index.ts

import { defineAction } from 'astro:actions';
import { z } from 'astro/zod';

export const server = {
  getGreeting: defineAction({
    input: z.object({
      // ...
    }),
    handler: async (input, context) => {
      context.rewrite('/')
      // ...
    }
  })
}

リライト (EN)の詳細を確認してください。

削除: スキーマ関数のシグネチャ（コンテンツローダーAPI）

実装PR：feat: loader.createSchema() (#14759)

Astro 5.xでは、コンテンツローダーがバリデーション用のZodスキーマオブジェクトを定義する代わりに、スキーマを関数として定義できました。これは設定オプションやAPIのイントロスペクションに基づいてスキーマを動的に生成する場合に便利でした。

Astro 6.0ではこのシグネチャが削除され、コンテンツローダー内でスキーマを動的に定義したい場合の代替として、新しいcreateSchema()プロパティが導入されました。

古い方法でスキーマ関数を提供すると、ローダーのスキーマが無視されている旨の警告メッセージがログに出力されますが、それ以外はスキーマが提供されていないかのようにローダーは動作し続けます。将来のメジャーバージョンでは、スキーマ関数を提供するローダーはエラーをスローし、使用できなくなります。

どうすればよいですか？

コンテンツローダーを作成していて、コレクションのschemaプロパティを動的に返す関数を使用している場合は、既存の関数を削除し、代わりに新しいcreateSchema()プロパティを使用してスキーマを定義してください。

たとえば、createSchema()と以前の関数ロジックでzod-to-tsを直接使用することで、Astroの以前の動作を再現できます。

import type { Loader } from 'astro/loaders'
import { createTypeAlias, zodToTs } from 'zod-to-ts'
import { getSchemaFromApi } from './utils'

function myLoader() {
  return {
    name: 'my-loader',
    load: async (context) => {
      // ...
    },
    schema: async () => await getSchemaFromApi(),
    createSchema: async () => {
      const schema = await getSchemaFromApi()
      const identifier = 'Entry'
      const { node } = zodToTs(schema, identifier)
      const typeAlias = createTypeAlias(node, identifier)

      return {
        schema,
        types: `export ${typeAlias}`
      }
    }
  } satisfies Loader
}

コンテンツローダーAPIリファレンスのcreateSchema() (EN)の詳細を確認してください。

削除: testセッションドライバー

実装PR：feat(sessions): drivers (#15006)

Astro 5.xでは、内部のtestセッションドライバーがAstro設定の型定義に含まれていましたが、公開を意図したものではありませんでした。

Astro 6.0では、context.sessionのテストに内部的に使用されなくなったため、testセッションドライバーが削除されました。

どうすればよいですか？

この内部APIを使用している可能性は低いですが、使用している場合はtestセッションドライバーの使用箇所をすべて削除してください。

astro.config.mjs

import { defineConfig } from 'astro/config'
import { createMockStorage } from './utils'

export default defineConfig({
  session: {
    driver: 'test',
    options: {
      mockStorage: createMockStorage()
    }
  }
})

セッションドライバーAPI (EN)の詳細を確認してください。

削除: CommonJS設定ファイルのサポート

実装PR：Drop cjs config support (#15192)

Astro 5.xでは、Astroの設定ファイルに.mjs、.js、.ts、.mts、.cjs、.ctsのいずれかの拡張子を使用できました。

Astro 6.0では.cjsと.ctsの拡張子のサポートが削除されました。

どうすればよいですか？

astro.config.cjsまたはastro.config.ctsファイルがある場合は、サポートされている拡張子（.mjs、.js、.ts、.mts）に変更してください。

Astro設定ファイルの詳細を確認してください。

実験的フラグ

実験的フラグを使うと、開発初期段階の機能を有効にできます。Astroはデフォルト動作への破壊的な変更をテストするために実験的フラグを使用することもあります。以下の実験的フラグはAstro 6.0で削除され、安定版となったか、新しいデフォルト動作になりました。

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

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
    csp: true,
    fonts: true,
    liveContentCollections: true,
    preserveScriptOrder: true,
    staticImportMetaEnv: true,
    headingIdCompat: true,
    failOnPrerenderConflict: true
  },
})

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

• csp（Content Security Policyの詳細については、security.csp設定リファレンス (EN)を確認してください。）
• fonts（プロジェクトへのカスタムフォントの追加については、更新されたフォントガイド (EN)を確認してください。）
• liveContentCollections（ライブコレクションについては、更新されたコンテンツコレクションドキュメント (EN)を確認してください。）
• failOnPrerenderConflict（新しいprerenderConflictBehavior (EN)設定オプションを確認してください。）

新しいデフォルトまたは推奨される動作:

• preserveScriptOrder（デフォルトの<script>と<style>の動作の破壊的な変更については以下を確認してください。）
• staticImportMetaEnv（import.meta.envの破壊的な変更については以下を確認してください。）
• headingIdCompat（MarkdownのヘッディングID生成の破壊的な変更については以下を確認してください。）

v6.0のブログ記事で新機能などの詳細を確認してください。

デフォルト値の変更

Astro v6.0では一部のデフォルト動作が変更されており、プロジェクトのコードに更新が必要になる場合があります。

ほとんどの場合、既存のプロジェクトのデプロイを確認し、期待どおりに動作し続けていることを確かめて、必要に応じてコードを更新するだけで済みます。場合によっては、以前のデフォルト動作を維持するための設定オプションが用意されていることもあります。

変更: i18n.routing.redirectToDefaultLocaleのデフォルト値

実装PR：feat(astro)!: update i18n.redirectToDefaultLocale default (#14406)

Astro v5.0では、i18n.routing.redirectToDefaultLocaleのデフォルト値はtrueでした。i18n.routing.prefixDefaultLocaleのデフォルト値falseと組み合わさると、リダイレクトが無限ループを引き起こす可能性がありました。

Astro v6.0では、i18n.routing.redirectToDefaultLocaleのデフォルト値がfalseに変更されました。また、i18n.routing.prefixDefaultLocaleがtrueに設定されている場合にのみ使用できるようになりました。

どうすればよいですか？

Astroのi18n設定を確認してください。プロジェクトの以前の動作を維持するために、redirectToDefaultLocaleとprefixDefaultLocaleの値を明示的に設定する必要がある場合があります。

astro.config.mjs

import { defineConfig } from 'astro/config';

export default defineConfig({
  i18n: {
    routing: {
      prefixDefaultLocale: true,
      redirectToDefaultLocale: true
    }
  }
})

手動ルーティングを使用している場合は、ミドルウェアの設定も更新が必要になることがあります。

src/middleware.js

import { middleware } from "astro:i18n"; // Astro独自のi18nルーティング設定

export const onRequest = middleware({
  prefixDefaultLocale: false,
  prefixDefaultLocale: true,
  redirectToDefaultLocale: true,
})

国際化のルーティング (EN)の詳細を確認してください。

変更: <script>と<style>タグが定義された順序でレンダリングされるように

実装PR：feat: stabilize experimental preserveScriptOrder option (#14480)

Astro v5.5では、複数の<style>と<script>タグをソースコードで宣言された順序でレンダリングするためのexperimental.preserveScriptOrderフラグが導入されました。Astro 5.xでは、生成されるHTML出力でこれらの順序が逆転していました。これにより、たとえばサイトのビルド時に、先に定義されたスタイルタグによってCSSスタイルが上書きされるなど、予期しない結果が生じることがありました。

Astro 6.0ではこの実験的フラグが削除され、Astroの新しいデフォルト動作になりました。スクリプトとスタイルはコード内で定義された順序でレンダリングされます。

どうすればよいですか？

この実験的機能を以前使用していた場合は、フラグがなくなったため設定から実験的フラグを削除する必要があります。

<script>と<style>タグが意図どおりに動作していることを確認してください。順序を逆にする必要があるかもしれません。

src/components/MyComponent.astro

<p>I am a component</p>
<style>
  body {
    background: red;
    background: yellow;
  }
</style>
<style>
  body {
    background: yellow;
    background: red;
  }
</style>
<script>
    console.log("hello")
    console.log("world")
</script>
<script>
    console.log("world!")
    console.log("hello!")
</script>

script (EN)タグとstyle (EN)タグの使用方法の詳細を確認してください。

変更: レスポンシブ画像スタイルの出力方法

実装PR：support responsive images (#15407)

Astro 5.xでは、画像はランタイムに計算され、fitとposのレスポンシブ画像スタイルはstyle属性にインジェクトされていました。これはさまざまな理由からAstroのContent Security Policy（CSP）との互換性がありませんでした。

Astro 6では、プロジェクトの設定に基づいてビルド時に仮想モジュール内で画像スタイルを生成するようになりました。これにより、ハッシュクラスとdata-*属性を使用して画像にレスポンシブスタイルが適用されます。

どうすればよいですか？

画像が期待どおりにレンダリングされていることを目視で確認してください。これは実装の詳細であり、レスポンシブ画像の通常の使用には影響しないはずです。

ただし、以前生成されていたインラインスタイルに依存していた場合：

<img style="--fit: <value>; --pos: <value>" >

新しいdata-*属性に対応するようにプロジェクトのコードを更新する必要があります。

<img class="__a_HaSh350" data-astro-fit="value" data-astro-pos="value" >

破壊的な変更

以下の変更はAstro v6.0における破壊的な変更です。破壊的な変更には、一時的な後方互換性が提供される場合とされない場合があります。これらの機能を使用していた場合は、各項目で推奨される方式に従ってコードを更新する必要があるかもしれません。

変更: ファイル拡張子を持つエンドポイントに末尾スラッシュ付きでアクセスできなくなった

実装PR：feat!: trailing slash never for endpoints with file extension (#14457)

Astro v5.0では、URLがファイル拡張子で終わるカスタムエンドポイント（例：/src/pages/sitemap.xml.ts）に、build.trailingSlashの設定値に関係なく、末尾スラッシュあり（/sitemap.xml/）でもなし（/sitemap.xml）でもアクセスできました。

Astro v6.0では、これらのエンドポイントには末尾スラッシュなしでのみアクセスできます。これはbuild.trailingSlashの設定に関係なく適用されます。

どうすればよいですか？

URLにファイル拡張子を含むカスタムエンドポイントへのリンクを確認し、末尾スラッシュを削除してください。

src/pages/index.astro

<a href="/sitemap.xml/">Sitemap</a>
<a href="/sitemap.xml">Sitemap</a>

カスタムエンドポイント (EN)の詳細を確認してください。

変更: import.meta.envの値が常にインライン化されるように

実装PR：feat: stabilize static import meta env (#14485)

Astro 5.13では、import.meta.envへの直接アクセス時の動作をViteの環境変数の扱いと揃え、import.meta.envの値が常にインライン化されるようにするexperimental.staticImportMetaEnvフラグが導入されました。

Astro 5.xでは、公開されていない環境変数はprocess.envへの参照に置き換えられていました。さらに、import.meta.envを通じて使用される環境変数の値の型が変換されることがあり、文字列"true"が真偽値に、"1"が数値に変換されるなど、一部の値に正しくアクセスできない場合がありました。

Astro 6ではこの実験的フラグが削除され、Astroの新しいデフォルト動作になりました。import.meta.envの値は常にインライン化され、型の強制変換はおこなわれません。

どうすればよいですか？

この実験的機能を以前使用していた場合は、フラグがなくなったため設定から実験的フラグを削除する必要があります。

型の強制変換に依存していた場合は、手動で変換するようにコードを更新する必要があるかもしれません。

src/components/MyComponent.astro

const enabled: boolean = import.meta.env.ENABLED;
const enabled: boolean = import.meta.env.ENABLED === "true";

process.envへの変換に依存していた場合は、手動でprocess.envを使用するようにコードを更新する必要があるかもしれません。

src/components/MyComponent.astro

const enabled: boolean = import.meta.env.DB_PASSWORD;
const enabled: boolean = process.env.DB_PASSWORD;

型の更新も必要になる場合があります。

src/env.d.ts

interface ImportMetaEnv {
  readonly PUBLIC_POKEAPI: string;
  readonly DB_PASSWORD: string;
  readonly ENABLED: boolean;
  readonly ENABLED: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

namespace NodeJS {
  interface ProcessEnv {
    DB_PASSWORD: string;
  }
}

Astroで環境変数をより細かく制御する必要がある場合は、astro:envの使用を推奨します。

astro:envを含むAstroの環境変数 (EN)の詳細を確認してください。

変更: デフォルト画像サービスでのクロップがデフォルトに

実装PR：feat(assets): Always allow cropping and never upscale (#14629)

Astro 5.0では、デフォルト画像サービスはfitオプションが指定された場合にのみクロップを適用していました。

Astro 6.0では、fitオプションを設定しなくてもデフォルトでクロップが適用されます。

どうすればよいですか？

fitプロパティは引き続き有効なため、既存のクロップされた画像に変更は不要です。ただし、画像をクロップするためにfitをcontain（デフォルト値）に設定していた場合は、このオプションを削除してもwidthとheightの指定だけで同じクロップ動作を実現できます。

src/components/MyImage.astro

---
import { Image } from 'astro:assets';
import myImage from '../assets/photo.jpg';
---
<Image src={myImage} width={400} height={300} fit="contain" />
<Image src={myImage} width={400} height={300} />

変更: デフォルトの画像サービスで画像がアップスケールされなくなった

実装PR：feat(assets): Always allow cropping and never upscale (#14629)

Astro 5.xでは、リクエストされたサイズが元の画像より大きい場合、デフォルトの画像サービスが画像をアップスケールしていました。

Astro 6.0ではこの動作が削除されました。デフォルトの画像サービスは画像をアップスケールしません。

どうすればよいですか？

画像を確認し、必要に応じてサイズを更新してください。画像のアップスケールが必要な場合は、手動でアップスケールするか、アップスケールをサポートするカスタム画像サービスの使用を検討してください。

変更: SVGのラスタライズ

実装PR：add support for SVG rasterization (#15180)

Astro v5.xでは、Astroのデフォルト画像サービスであるSharpはSVGファイルをラスターファイル（PNG、WebPなど）に変換できませんでした。そのため、<Image />コンポーネントはSVGファイルの最適化・変換時にformatに設定された値を無視していました。

Astro 6.0ではSVGのラスタライズがサポートされました。ただし多くの制約があり、たとえば埋め込みフォントを含むSVGは正しく変換されない場合があります。formatプロパティが設定されている場合、画像サービスはSVG画像の変換を試みるようになりました。

どうすればよいですか？

以前、画像サービスがSVGの変換を自動的にスキップすることに依存していた場合は、SVGがラスター画像に変換されるのを避けるため、事前に画像のフォーマットを確認する必要があります。

<Image src={imageThatMightBeAnSvg} format="avif" alt="example" />

<Image
  src={imageThatMightBeAnSvg}
  format={imageThatMightBeAnSvg.format === "svg" ? "svg" : "avif"}
  alt="example"
/>

format画像プロパティ (EN)の詳細を確認してください。

変更: getImage()がクライアントで呼び出されるとエラーをスローするように

実装PR：feat: disallow getImage on the client (#15800)

Astro 5.xでは、クライアントでastro:assetsのgetImage()を呼び出すと、エラーなく失敗するか、不正な結果が返されていました。

Astro 6.0では、クライアントでgetImage()が呼び出されるとランタイムエラーがスローされます。

どうすればよいですか？

getImage()はサーバーで呼び出し、結果のsrcをクライアントに渡すようにしてください。

src/components/ClientImage.astro

---
import { getImage } from "astro:assets";
import myBackground from "../background.png";

const optimizedBackground = await getImage({ src: myBackground, format: "avif" });
---

<div id="background" data-src={optimizedBackground.src}></div>

<script>
  const src = document.getElementById("background").dataset.src;
  // 必要に応じてクライアント側でsrcを使用
</script>

完全な例については、getImage()による画像の生成 (EN)を確認してください。

変更: MarkdownのヘッディングID生成

実装PR：feat!: stabilize experimental.headingIdCompat (#14494)

Astro 5.xでは、Markdownのデフォルト処理で、特殊文字で終わるセクション見出しのIDから末尾のハイフンが除去されていました。これによりIDの値はきれいになりましたが、プラットフォーム間でMarkdownをレンダリングする際に互換性の問題が生じる可能性がありました。

Astro 5.5では、人気のあるgithub-sluggerパッケージを使用して、AstroがMarkdownの見出しに対して生成するIDをGitHubやnpmなどの一般的なプラットフォームと互換性のあるものにするためのexperimental.headingIdCompatフラグが導入されました。

Astro 6.0ではこの実験的フラグが削除され、Astroの新しいデフォルト動作になりました。特殊文字で終わる見出しのIDから末尾のハイフンが除去されなくなりました。

どうすればよいですか？

見出しへ手動でリンクしている場合は、アンカーリンクの値に新しい末尾ハイフンを追加する必要があるかもしれません。たとえば、次のMarkdownの見出し

## `<Picture />`

は、見出しのidに末尾ハイフンが付いた以下のHTMLを生成するようになります。

<h2 id="picture-"><code>&lt;Picture /&gt;</code></h2>

リンクは以下のように記述する必要があります。

詳細は[Pictureコンポーネント](/ja/guides/images/#picture-)を確認してください。

末尾ハイフンを強制するためにこの実験的機能を以前使用していた場合は、フラグがなくなったため設定から実験的フラグを削除する必要があります。

互換性を強制するためにrehypeHeadingIdsプラグインを直接使用していた場合は、headingIdCompatオプションがなくなったため削除してください。

astro.config.mjs

import { defineConfig } from 'astro/config';
import { rehypeHeadingIds } from '@astrojs/markdown-remark';
import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';

export default defineConfig({
  markdown: {
    rehypePlugins: [
      [rehypeHeadingIds, { headingIdCompat: true }],
      [rehypeHeadingIds],
      otherPluginThatReliesOnHeadingIDs,
    ],
  },
});

後方互換性のために以前のID生成を維持したい場合は、Astro 5.xと同じ見出しIDを生成するカスタムrehypeプラグインを作成できます。これにより、末尾ハイフンを追加せずに既存のアンカーリンクを引き続き使用できます。

末尾ハイフンを除去するカスタムrehypeプラグインの作成

1. 必要な依存関係をインストールします。

   npm

   npm i github-slugger hast-util-heading-rank unist-util-visit hast-util-to-string

   pnpm

   pnpm add github-slugger hast-util-heading-rank unist-util-visit hast-util-to-string

   Yarn

   yarn add github-slugger hast-util-heading-rank unist-util-visit hast-util-to-string

2. Astro v5と同じ見出しIDを生成するカスタムrehypeプラグインを作成します。

   plugins/rehype-slug.mjs

   import GithubSlugger from 'github-slugger';
   import { headingRank } from 'hast-util-heading-rank';
   import { visit } from 'unist-util-visit';
   import { toString } from 'hast-util-to-string';
   
   const slugs = new GithubSlugger();
   
   export function rehypeSlug() {
     /**
      * @param {import('hast').Root} tree
      */
     return (tree) => {
       slugs.reset();
       visit(tree, 'element', (node) => {
         if (headingRank(node) && !node.properties.id) {
           let slug = slugs.slug(toString(node));
           // Astro v5以前と同様に末尾ハイフンを除去:
           if (slug.endsWith('-')) slug = slug.slice(0, -1);
           node.properties.id = slug;
         }
       });
     };
   }

3. astro.config.mjsのMarkdown設定にカスタムプラグインを追加します。

   astro.config.mjs

   import { defineConfig } from 'astro/config';
   import { rehypeSlug } from './plugins/rehype-slug';
   
   export default defineConfig({
     markdown: {
       rehypePlugins: [rehypeSlug],
     },
   });

ヘッディングID (EN)の詳細を確認してください。

変更: getStaticPaths()が数値型のparamsを返せなくなった

実装PR：fix!: disallow number in getStaticPaths params (#14586)

Astro 5.xでは、getStaticPaths()が数値型のparamsを返すことができ、Astroによって常に文字列化されていました。しかし、Astro.paramsの型と矛盾するため、混乱を招く可能性がありました。

Astro 6.0ではこの動作が削除されました。getStaticPaths()は文字列またはundefinedのparams値を返す必要があります。

どうすればよいですか？

getStaticPaths()を使用している動的ルートを確認し、数値のparamsを文字列に変換してください。

src/pages/post/[id]/[label].astro

---
export function getStaticPaths() {
  return [
    {
      params: {
        id: 1,
        id: "1",
        label: "foo",
      }
    },
    {
      params: {
        id: 2,
        id: "2",
        label: "bar",
      }
    },
  ]
}
---

getStaticPaths()を使用した動的SSGルート (EN)の詳細を確認してください。

変更: Vitestのクライアント環境でAstroコンポーネントをレンダリングできなくなった（コンテナAPI）

実装PR：feat: remove Vitest workaround for client environment (#14895)

Astro 5.xでは、クライアントでのAstroコンポーネントのレンダリングは禁止されていました。ただし、実験的なコンテナAPI (EN)を使用して、jsdomやhappy-domなどのVitestクライアント環境では一時的にこの動作が許可されていました。

Astro 6.0では、Vitestのクライアント環境でAstroコンポーネントをレンダリングする機能が削除されました。Astroコンポーネントをレンダリングするテストは、nodeのようなサーバー環境で実行する必要があります。

どうすればよいですか？

jsdomやhappy-domなどのクライアント環境でAstroコンポーネントをレンダリングするテストをVitestで実行している場合は、Vitestの設定をnode環境に更新してください。

vitest.config.ts

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'jsdom',
    environment: 'node',
  },
});

Astroコンポーネントのテストの詳細を確認してください。

変更: Rollup出力ファイル名の設定パス（Vite設定）

実装PR：feat: integrate vite environments (#14306)

Astro 5.xでは、クライアントアセットのカスタムRollup出力ファイル名オプションはvite.build.rollupOptions.outputで設定できました。

Astro 6.0では、クライアントビルドの出力設定がViteのクライアント環境にスコープされるようになりました。クライアントアセットのentryFileNames、chunkFileNames、またはassetFileNamesをカスタマイズしている場合は、vite.environments.client.build.rollupOptions.outputを使用してください。

どうすればよいですか？

設定をvite.build.rollupOptions.outputからvite.environments.client.build.rollupOptions.outputに移動してください。

astro.config.mjs

export default defineConfig({
  vite: {
    environments: {
      client: {
        build: {
          rollupOptions: {
            output: {
              entryFileNames: 'js/[name]-[hash].js',
            },
          },
        },
      },
    },
  },
});

変更: インテグレーションフックとHMRアクセスパターン（インテグレーションAPI）

実装PR：feat: integrate vite environments (#14306)

Astro 5.xでは、インテグレーションフックとHMRアクセスに特定のパターンが使用されていましたが、ViteのEnvironment APIとは互換性がない部分や、統合により改善できる部分がありました。

Astro 6.0では、ビルド設定と開発サーバーの操作にViteの新しいEnvironment APIを使用します。これは主にworkerdなどのランタイムでの開発モードを可能にしますが、一部のインテグレーションフックとHMRアクセスパターンが変更されています。

どうすればよいですか？

astro:build:setupを使用するインテグレーションの場合:

このフックは、ビルドターゲットごとに個別に呼び出されるのではなく、すべての環境（ssr、client、prerender）が設定された状態で一度だけ呼び出されるようになりました。targetパラメータを削除し、vite.environmentsを使用して特定の環境を設定してください。

my-integration.mjs

{
  hooks: {
    'astro:build:setup': ({ target, vite }) => {
      if (target === 'client') {
        vite.build.minify = false;
      }
    }
    'astro:build:setup': ({ vite }) => {
      vite.environments.client.build.minify = false;
    }
  }
}

開発ツールバーやHMRにアクセスするインテグレーションコードの場合:

server.hot.send()をserver.environments.client.hot.send()に置き換えてください。

server.hot.send(event)
server.environments.client.hot.send(event)

Vite Environment APIとAstroのインテグレーションフック (EN)の詳細を確認してください。

変更: SSRManifestインターフェースの構造（アダプターAPI）

実装PR：feat: integrate vite environments (#14306)

Astro 5.xでは、SSRManifestインターフェースのsrcDir、outDir、cacheDir、publicDir、buildClientDir、buildServerDirなどのパスプロパティはURL文字列でした。

Astro 6.0では、これらのパスプロパティがURL文字列からURLオブジェクトに変更されました。この変更にともない、マニフェストにはいくつかの新しいプロパティが追加され、他のプロパティは更新または削除されました。

どうすればよいですか？

これらのパスプロパティを文字列として扱っていた場合は、URLオブジェクトを処理するように変更する必要があります。たとえば以下のように、URLオブジェクトのhrefプロパティにアクセスする必要があります。

// 同じ形式（例："file:///path/to/src"）を取得するには、以下のように変更します:
const srcPath = manifest.srcDir;
const srcPath = manifest.srcDir.href;

hrefRootプロパティにアクセスしていた場合は、マニフェストから削除されたため、使用箇所を削除する必要があります。

serverIslandMappingsとsessionDriverの使用箇所も更新してください。これらは非同期メソッドになりました。

const mappings = manifest.serverIslandMappings;
const driver = manifest.sessionDriver;
const mappings = await manifest.serverIslandMappings?.();
const driver = await manifest.sessionDriver?.();

アダプターAPI (EN)の詳細を確認してください。

変更: スキーマの型が生成ではなく推論されるように（コンテンツローダーAPI）

実装PR：feat: loader.createSchema() (#14759)

Astro 5.xでは、コンテンツローダーによってスキーマが提供され、ユーザー定義のスキーマがない場合、コンテンツコレクションの型はzod-to-tsを使用して生成されていました。

Astro 6.0ではこの動作が削除されました。型はzod-to-tsで生成されなくなり、代わりに推論されます。

どうすればよいですか？

コンテンツローダーでschemaを指定している場合は、TypeScriptのsatisfies演算子を使用する必要があります。

import type { Loader } from 'astro/loaders'

function myLoader(): Loader {
function myLoader() {
  return {
    name: 'my-loader',
    load: async (context) => {
      // ...
    },
    schema: z.object({/* ... */})
  }
  } satisfies Loader
}

ローダーのスキーマ型の定義 (EN)の詳細を確認してください。

既知の問題

報告済みの問題の確認や、新しい問題の報告はAstroのGitHub Issuesからおこなってください。