Astro Adapter API
Astroは、SSR(サーバーサイドレンダリング)のために任意のクラウドプロバイダに簡単にデプロイできるように設計されています。この機能は、アダプターによって提供されているインテグレーションの一種です。既存のアダプターの使用方法については、SSRガイドをご覧ください。
アダプターとは
セクションタイトル: アダプターとはアダプターは、サーバーサイドレンダリングのエントリポイントを提供する特別な種類のインテグレーションです。アダプターは以下の2つのことを行います。
- リクエストを処理するためのホスト固有のAPIを実装します。
- ホストの規約に従ってビルドを設定します。
アダプターの構築
セクションタイトル: アダプターの構築アダプターはインテグレーションであり、インテグレーションが行えることは何でも行うことができます。
アダプターは、次のようにしてastro:config:done
フックでsetAdapter
APIを呼び出す必要があります。
setAdapter
に渡されるオブジェクトは以下のように定義されています。
プロパティの説明は次のとおりです。
- name: ログに使用されるアダプターのユニークな名前。
- serverEntrypoint: サーバーサイドレンダリングのエントリポイント。
- exports:
createExports
(以下で説明)と併用する場合の名前付きエクスポートの配列。 - adapterFeatures: アダプターがサポートする必要がある特定の機能を有効にするオブジェクト。これらの機能はビルドされた出力を変更し、アダプターは異なる出力を処理するための適切なロジックを実装する必要があります。
- supportedAstroFeatures: Astroの組み込み機能のマップ。これにより、Astroはアダプターがサポートできない、またはサポートしない機能を判断し、適切なエラーメッセージを提供できます。
サーバーエントリポイント
セクションタイトル: サーバーエントリポイントAstroのアダプターAPIは、任意のタイプのホストと連携できるように設計されており、ホストのAPIに適合する柔軟な方法を提供します。
エクスポート
セクションタイトル: エクスポート一部のサーバーレスホストでは、handler
のような関数をエクスポートすることが求められます。
アダプターAPIを使用すると、serverEntrypoint
でcreateExports
を実装することでこれを実現できます。
その後、setAdapter
を呼び出すインテグレーションで、この名前をexports
で指定します。
サーバーの起動について
セクションタイトル: サーバーの起動について一部のホスティング環境では、サーバーを自分で起動する必要があります。例えば、特定のポートでリッスンを開始するなどです。このような環境に対応するため、アダプターAPIではstart
関数をエクスポートできるようになっています。この関数は、バンドルされたスクリプトが実行されたときに呼び出されます。
astro/app
モジュールについて
セクションタイトル: astro/appモジュールについてこのモジュールは、astro build
コマンドで事前にビルドされたページをレンダリングするために使用します。Astroは標準のRequestオブジェクトとResponseオブジェクトを使用します。独自のリクエスト/レスポンスAPIを持つホスティング環境の場合、アダプター内でこれらの標準オブジェクトに変換する処理を実装する必要があります。
このモジュールは以下のメソッドを提供します。
app.render(request: Request, options?: RenderOptions)
セクションタイトル: app.render(request: Request, options?: RenderOptions)このメソッドは、リクエストに対応するAstroページを呼び出してレンダリングし、Responseオブジェクトを含むPromiseを返します。これはページをレンダリングしないAPIルートでも同様に機能します。
RenderOptions
について
セクションタイトル: RenderOptionsについてapp.render()
メソッドは、必須のrequest
引数と、オプションのRenderOptions
オブジェクトを受け取ります。RenderOptions
にはaddCookieHeader
、clientAddress
、locals
、routeData
といったオプションが含まれます。
addCookieHeader
オプション
セクションタイトル: addCookieHeaderオプションこのオプションは、Astro.cookie.set()
で設定されたすべてのクッキーを自動的にレスポンスヘッダーに追加するかどうかを指定します。
true
に設定すると、クッキーはレスポンスのSet-Cookie
ヘッダーにコンマ区切りのキーと値のペアとして追加されます。標準のresponse.headers.getSetCookie()
APIを使用して個別に読み取ることができます。
false
(デフォルト値)に設定すると、クッキーはApp.getSetCookieFromResponse(response)
メソッドを通じてのみ取得できます。
clientAddress
オプション
セクションタイトル: clientAddressオプションこのオプションで指定したクライアントのIPアドレスは、ページ内ではAstro.clientAddress
として、APIルートとミドルウェア内ではctx.clientAddress
として利用できます。
以下は、x-forwarded-for
ヘッダーの値を読み取り、それをclientAddress
として設定する例です。この値はAstro.clientAddress
としてユーザーが利用できるようになります。
locals
オプション
セクションタイトル: localsオプションlocals
は、リクエストの処理中に情報を保存したりアクセスしたりするためのcontext.locals
オブジェクトです。
例えば、次のようなケースで使用できます。x-private-header
というヘッダーの値を読み取り、それをオブジェクトとして解析してlocals
に渡します。こうすることで、その情報を任意のミドルウェア関数で利用できるようになります。
routeData
オプション
セクションタイトル: routeDataオプションレンダリングするルートが事前に分かっている場合は、このオプションでrouteData
を指定できます。これにより、ルートを決定するためのapp.match
の内部呼び出しをスキップできます。
app.match(request)
メソッド
セクションタイトル: app.match(request)メソッドこのメソッドは、受け取ったリクエストがAstroアプリのルーティングルールに合致するかどうかを判断するために使用します。
通常は.match
を使わずに直接app.render(request)
を呼び出せます。Astroは404.astro
ファイルがあれば、自動的に404エラーを処理します。ただし、404エラーを独自の方法で処理したい場合は、app.match(request)
を使用してください。
astro add
コマンドでのインストールを可能にする
セクションタイトル: astro addコマンドでのインストールを可能にするastro add
コマンドを使うと、ユーザーは簡単にインテグレーション機能やアダプターをプロジェクトに追加できます。自作のアダプターをこのコマンドでインストールできるようにするには、package.json
ファイルのkeywords
フィールドにastro-adapter
を追加してください。
アダプターをnpmに公開すると、ユーザーはastro add example
コマンドを実行するだけで、package.json
に指定されたピア依存関係と共にパッケージをインストールできます。ただし、プロジェクトの設定ファイルの更新は手動で行うよう、ユーザーに指示する必要があります。
Astroの機能について
セクションタイトル: Astroの機能について
追加:
astro@3.0.0
Astroの機能は、アダプターがどの機能をサポートできるか、そしてそのサポートレベルをAstroに伝えるための仕組みです。
これらの機能を使用すると、Astroは以下の処理を行います。
- 特定の検証を実行します
- 状況に応じたログを出力します
これらの処理は、サポートされている機能、サポートされていない機能、そのサポートレベル、そしてユーザーの設定に基づいて実行されます。
例えば、次の設定は、このアダプターがアセット機能を実験的にサポートしているものの、SharpやSquooshといった組み込みサービスとは互換性がないことをAstroに伝えます。
この場合、Astroはターミナルに警告を表示します。
また、アセットに使用するサービスがアダプターと互換性がない場合は、エラーも表示します。
アダプターの機能について
セクションタイトル: アダプターの機能についてアダプターの機能は、出力されるファイルの内容を変更する一連の機能です。アダプターがこれらの機能を有効にすると、特定のフック内で追加情報を取得できます。
functionPerRoute
機能
セクションタイトル: functionPerRoute機能この機能は、SSR(サーバーサイドレンダリング)を使用する場合にのみ有効になります。デフォルトでは、Astroは単一のentry.mjs
ファイルを生成し、このファイルが各リクエストに対してレンダリングされたページを出力します。
functionPerRoute
をtrue
に設定すると、Astroはプロジェクトで定義された各ルートに対して個別のファイルを作成します。
生成される各ファイルは1つのページのみをレンダリングします。これらのページファイルはdist/pages/
ディレクトリ(またはoutDir
で指定されたディレクトリ内の/pages/
)に出力され、src/pages/
ディレクトリと同じファイル構造を維持します。
例えば、pages/
ディレクトリ内のファイル構造は、ビルド後のsrc/pages/
のページファイルの構造を反映します。
ディレクトリdist/
ディレクトリpages/
ディレクトリblog/
- entry._slug_.astro.mjs
- entry.about.astro.mjs
- entry.index.astro.mjs
この機能を有効にするには、アダプターにtrue
を渡します。
その後、astro:build:ssr
フックを使用します。このフックはentryPoints
オブジェクトを提供し、ページのルートとビルド後に生成された実際のファイルをマッピングします。
entryFile
はURL
型で、ファイルシステム上の実際のファイルパスを表します。つまり、コードが実行されるOSによってパスが変わる可能性があります。
サーバーレス環境での動作について
セクションタイトル: サーバーレス環境での動作についてサーバーレス環境でfunctionPerRoute: true
を設定すると、各ルートに対して個別のJavaScriptファイル(ハンドラー)が作成されます。このハンドラーは、使用するホスティングプラットフォームによってlambda、function、pageなど、さまざまな名前で呼ばれることがあります。
これらの各ルートは、ハンドラーが実行される際にコールドスタートの影響を受ける可能性があり、これにより多少の遅延が生じることがあります。この遅延の程度はさまざまな要因に左右されます。
一方、functionPerRoute: false
に設定した場合、すべてのルートのレンダリングを1つのハンドラーが担当します。このハンドラーが最初に呼び出されるときにはコールドスタートの影響を受けますが、それ以降のルートは遅延なく機能するはずです。ただし、この設定ではfunctionPerRoute: true
で得られるコード分割の利点は失われてしまいます。
プロジェクトに最適なfunctionPerRoute
の設定を選択するためには、使用するホスティングプラットフォームの仕組みをよく理解することが重要です。
edgeMiddleware
機能について
セクションタイトル: edgeMiddleware機能についてこの機能は、SSR(サーバーサイドレンダリング)のミドルウェアコードをビルド時にバンドル(まとめて)するかどうかを指定します。
この機能を有効にすると、ビルド中にミドルウェアコードがバンドルされ、すべてのページで個別にインポートされるのを防ぐことができます。
この機能を使用する場合、astro:build:ssr
フックを利用します。このフックはmiddlewareEntryPoint
を提供します。これはファイルシステム上の実際のファイルへのURL
です。