Astro を Zephyr 用に設定する
セットアップ
サイトの既存の astro.config.*、その output モードとアダプター、インストールされている astro のバージョンを編集前に確認してください。既存のインテグレーションとオプションは保持してください。zephyr-astro-integration がない場合は、依存関係の変更が許可されている場合にのみインストールしてください。これはビルド時にのみ必要なため、開発依存関係で十分です。
インストールされるパッケージは、astro のピア依存関係として ^4.0.0 || ^5.15.8 || ^6.4.6 || ^7.0.7 を宣言しており、Astro が提供する Vite のバージョンを使用します。withZephyr() を integrations の最後のエントリとして追加します：
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import sitemap from '@astrojs/sitemap';
import { withZephyr } from 'zephyr-astro-integration';
export default defineConfig({
site: 'https://example.com',
integrations: [mdx(), sitemap(), withZephyr()],
});
Astro は astro:build:done フックをインテグレーションごとにリスト順に1つずつ実行し、Zephyr はそのフックからアップロードを行います。このインテグレーションを最後に配置することで、sitemap など、先行するインテグレーションによって書き込まれたファイルがアップロード前に存在するようになります。デフォルトエクスポートは同じ withZephyr 関数です。vite-plugin-zephyr を vite.plugins に追加しないでください。インテグレーションがすでに公開を担当しています。
モジュールフェデレーション
このインテグレーションはモジュールフェデレーションを設定せず、zephyr:dependencies をリモート URL に解決しません。mfConfigs および federation オプションはそのまま転送される公開メタデータであり、TAP パッケージにのみ必要です。設定する前に公開の詳細を読んでください。共有の zephyr-module-federation ガイドでは、プロジェクト間のホスト・リモートモデルについて説明しています。
静的出力のみ
このインテグレーションは、Astro が astro:build:done に渡すディレクトリをアップロードし、サーバーのエントリポイントやスナップショットタイプを送信することはありません。そのディレクトリはクライアント出力であるため、静的サイトを公開します。output: 'server' またはアダプターを使用している場合、クライアントファイルとプリレンダリングされたファイルのみが公開されます。オンデマンドルート、API エンドポイント、ミドルウェアは公開されません。このインテグレーションを SSR デプロイパスとして提示せず、ユーザーのアダプターを許可なく削除して適合させようとしないでください。代わりに制限事項を報告してください。
このインテグレーションは、サイトの .env ファイルから ZE_PUBLIC_* 値も読み込み、import.meta.env.ZE_PUBLIC_* および process.env.ZE_PUBLIC_* の読み取りを書き換えることで、ビルド後に環境が上書きできるようにします。共有の zephyr-core ガイドでそのモデルについて説明しています。
誤解を招く修正を避ける
- 成功した
astro buildを公開とみなさないでください。ビルドフックでの Zephyr エラーはログに記録され、ZE_FAIL_BUILD=trueが設定されていない限りビルドは続行されます。ただちにスローされるのは無効なtargetのみです。 - 通常のサイトに
target: 'tap-app'を設定しないでください。TAP はZE_PUBLIC_*の書き換えを無効にし、ペアとなるフェデレーションメタデータが必要です。 - ソースマップが公開されていると想定しないでください。
.mapファイルは通常のサイトではスキップされます。 ZE_PUBLIC_*に認証情報を入れないでください。これらの値はクライアントから見えます。
完了の確認
認可されたビルドを、サイトの既存のパッケージランナーで実行してください。出力ディレクトリに期待通りのページとアセットが含まれていること、および Zephyr がバージョン URL 付きで公開成功を報告していることを確認してください。認証情報なしでのビルドは、ローカル出力の正しさを確認できますが、実際のデプロイの成功を確認することはできません。その違いを報告し、サーバーでレンダリングされるルートが公開対象外であることを明確に述べてください。
失敗した場合は、実行可能なエラーを残し、一致する設定を修正してください。サイトの出力モードを黙って変更したり、エラーを抑制したり、部分的なビルドがデプロイされたと主張したりしないでください。