ミドルウェア
ミドルウェアにより、リクエストとレスポンスをインターセプトし、ページやエンドポイントがレンダリングされる直前に動的に振る舞いを注入できます。こうしたレンダリングは、ページが事前レンダリングされる場合にはビルド時におこなわれますが、オンデマンドにレンダリングされるページの場合は、ルートへのリクエスト時におこなわれます。
また、ミドルウェアを使って、すべてのAstroコンポーネントとAPIエンドポイントで利用可能なlocals
オブジェクトを変更し、リクエスト固有の情報を各エンドポイントとページで設定・共有することもできます。このオブジェクトは、このミドルウェアがビルド時に実行される場合でも利用できます。
基本的な使い方
セクションタイトル: 基本的な使い方-
src/middleware.js|ts
というファイルを作成します。(あるいは、src/middleware/index.js|ts
を作成しても構いません。) -
このファイルの中で、
context
オブジェクトとnext()
関数を受け取るonRequest()
関数をエクスポートします。これをデフォルトエクスポートにしてはいけません。 -
.astro
ファイルの中で、Astro.locals
を使ってレスポンスデータにアクセスします。
context
オブジェクト
セクションタイトル: contextオブジェクトcontext
オブジェクトには、レンダリング中に他のミドルウェア、APIルート、.astro
ルートで利用可能な情報が含まれています。
これはonRequest()
に渡されるオプション引数で、locals
オブジェクトや、レンダリング中に共有されるその他のプロパティを含む場合があります。たとえばcontext
オブジェクトには、認証に使用されるクッキーを含められます。
context.locals
にデータを保存する
セクションタイトル: context.localsにデータを保存するcontext.locals
は、ミドルウェア内で変更可能なオブジェクトです。
このlocals
オブジェクトは、リクエスト処理のプロセスを通じて受け渡されていき、APIContext
とAstroGlobal
のプロパティとして利用できます。これにより、ミドルウェア、APIルート、.astro
ページ間でデータを共有できます。ユーザーデータなど、リクエスト固有のデータを各レンダリングステップをまたいで保持する際に役立ちます。
インテグレーションは、locals
オブジェクトを介してプロパティを設定し、機能を提供する場合があります。インテグレーションを使用している場合は、そのドキュメントを確認して、プロパティを上書きしていないか、不要な操作をしていないかを確認してください。
locals
には、文字列、数値、さらには関数やマップといった複雑なデータ型など、どんな型のデータでも格納できます。
そして、任意の.astro
ファイル内でAstro.locals
によりこの情報を利用できます。
locals
は単一のAstroルートの中で生成・消滅します。ページルートがレンダリングされると、locals
はもう存在せず、その後また新しいものが作成されます。複数のページリクエストをまたいで保持されるべき情報は、別の場所に保存する必要があります。
locals
の値はランタイムに上書きできません。これをおこなうと、ユーザーが保存した情報がすべて消去される可能性があるためです。dev
モードにおいてAstroはこれを監視し、locals
が上書きされた場合にエラーをスローします。
センシティブな情報を消去する例
セクションタイトル: センシティブな情報を消去する例以下の例では、ミドルウェアを使用して「極秘情報」という文字列を「削除済み」という語に置き換えることで、変更されたHTMLをページにレンダリングできるようにします。
ミドルウェアの型
セクションタイトル: ミドルウェアの型defineMiddleware()
ユーティリティ関数をインポートして使用すると、型安全性を確保できます。
JsDocにより型を記述している場合は、MiddlewareHandler
を使用できます。
Astro.locals
内の情報に型を付け、.astro
ファイルとミドルウェアの両コードで自動補完を有効化するには、env.d.ts
ファイルでグローバル名前空間を宣言します。
これにより、ミドルウェアファイル内で自動補完が有効になり、型安全性が確保されます。
ミドルウェアを連結する
セクションタイトル: ミドルウェアを連結するsequence()
を使用して、複数のミドルウェアを指定した順序で連結できます。
これにより、以下の順序でコンソールに出力されます。
エラーページ
セクションタイトル: エラーページミドルウェアは、オンデマンドレンダリングされるすべてのページに対して実行を試みます。これにはAstroのデフォルト(空白)の404ページや、カスタムの404ページが含まれます。ただし、そのコードが実行されるかどうかはアダプターによって決定されます。一部のアダプターは、プラットフォーム固有のエラーページを代わりに提供する場合があります。
ミドルウェアはまた、カスタムの500ページを含む500エラーページを提供する前にも実行を試みます。ただし、ミドルウェア自体の実行中にサーバーエラーが発生した場合を除きます。ミドルウェアが正常に実行されない場合、500ページをレンダリングするためにAstro.locals
にアクセスすることはできません。