ミドルウェア

ミドルウェアにより、リクエストとレスポンスをインターセプトし、ページやエンドポイントがレンダリングされる直前に動的に振る舞いを注入できます。

また、すべてのAstroコンポーネントとAPIエンドポイントで利用可能なlocalsオブジェクトを変更し、リクエスト固有の情報を各エンドポイントとページで設定・共有することもできます。

ミドルウェアはSSGとSSRのAstroプロジェクトの両方で利用可能です。

基本的な使い方

src/middleware.js|ts というファイルを作成します。（あるいは、src/middleware/index.js|ts を作成しても構いません。）

このファイルの中で、onRequest()関数をエクスポートします。これをデフォルトエクスポートにしてはいけません。

export function onRequest ({ locals, request }, next) {
    // レスポンスデータをリクエストからインターセプトします
    // 必要に応じて、`locals`を改変してレスポンスを加工します
    locals.title = "新しいタイトル";

    // Responseか`next()`の結果を返します
    return next();
};

.astroファイルの中で、Astro.localsを使ってレスポンスデータにアクセスします。

---
const data = Astro.locals;
---
<h1>{data.title}</h1>
<p>この{data.property}はミドルウェアで設定しました。</p>

ミドルウェアの型

defineMiddleware()ユーティリティ関数をインポートして使用すると、型安全性を確保できます。

import { defineMiddleware } from "astro:middleware";

// `context`と`next`は自動的に型付けされます
export const onRequest = defineMiddleware((context, next) => {

});

JsDocにより型を記述している場合は、MiddlewareRequestHandlerを使用できます。

/**
 * @type {import("astro").MiddlewareResponseHandler}
 */
// `context`と`next`は自動的に型付けされます
export const onRequest = (context, next) => {

};

Astro.locals内の情報に型を付け、.astroファイルとミドルウェアの両コードで自動補完を有効化するには、env.d.tsファイルでグローバル名前空間を宣言します。

/// <reference types="astro/client" />
declare namespace App {
    interface Locals {
        user: {
            name: string
        },
        welcomeTitle: () => string,
        orders: Map<string, object>
    }
}

これにより、ミドルウェアファイル内で自動補完が有効になり、型安全性が確保されます。

Astro.localsには、文字列、数値、さらには関数やマップといった複雑なデータ型など、どんな型のデータでも格納できます。

export function onRequest ({ locals, request }, next) {
    // レスポンスデータをリクエストからインターセプトします
    // 必要に応じて、`locals`を改変してレスポンスを加工します
    locals.user.name = "John Wick";
    locals.welcomeTitle = () => {
        return "おかえりなさい " + locals.user.name;
    };

    // Responseか`next()`の結果を返します
    return next();
};

そして、任意の.astroファイル内でこの情報を利用できます。

---
const title = Astro.locals.welcomeTitle();
const orders = Array.from(Astro.locals.orders.entries());
---
<h1>{title}</h1>
<p>この{data.property}はミドルウェアで設定しました。</p>
<ul>
    {orders.map(order => {
        return <li>{/* 各値を使って何かします */}</li>;
    })}
</ul>

センシティブな情報を消去する例

以下の例では、ミドルウェアを使用して「極秘情報」という文字列を「削除済み」という語に置き換えることで、変更されたHTMLをページにレンダリングできるようにします。

export const onRequest = async (context, next) => {
    const response = await next();
    const html = await response.text();
    const redactedHtml = html.replaceAll("極秘情報", "削除済み");

    return new Response(redactedHtml, {
        status: 200,
        headers: response.headers
    });
};

ミドルウェアを連結する

sequence()を使用して、複数のミドルウェアを指定した順序で連結できます。

import { sequence } from "astro:middleware";

async function validation(_, next) {
    console.log("validationリクエスト");
    const response = await next();
    console.log("validationレスポンス");
    return response;
}

async function auth(_, next) {
    console.log("authリクエスト");
    const response = await next();
    console.log("authレスポンス");
    return response;
}

async function greeting(_, next) {
    console.log("greetingリクエスト");
    const response = await next();
    console.log("greetingレスポンス");
    return response;
}

export const onRequest = sequence(validation, auth, greeting);

これにより、以下の順序でコンソールに出力されます。

validationリクエスト
authリクエスト
greetingリクエスト
greetingレスポンス
authレスポンス
validationレスポンス

APIリファレンス

`onRequest()`

src/middleware.jsからエクスポートされる必須の関数で、各ページやAPIルートのレンダリングの前に呼び出されます。2つのオプション引数、contextとnext()を受け取ります。onRequest()は、Responseを返す必要があります。直接、またはnext()を呼び出してください。

`context`

レンダリング処理中に、他のミドルウェア、APIルート、.astroルートで利用可能な情報を含むオブジェクトです。

これはonRequest()に渡されるオプション引数で、localsオブジェクトや、レンダリング中に共有されるその他のプロパティを含む場合があります。たとえばcontextオブジェクトには、認証に使用されるクッキーを含められます。

これはAPIルートに渡されるcontextオブジェクトと同じものです。

`next()`

RequestのResponseをインターセプトする（読み取り、変更を加える）か、ミドルウェアのチェーン内の「次の」ミドルウェアを呼び出してResponseを返すための関数です。たとえばこの関数を用いて、レスポンスのHTML本文を変更できます。

これはonRequest()のオプション引数で、ミドルウェアが返す必要のあるResponseを提供します。

`locals`

ミドルウェア内で変更可能な、Responseからのデータを含むオブジェクトです。

このlocalsオブジェクトは、リクエスト処理のプロセスを通じて転送されていき、APIContextとAstroGlobalのプロパティとして利用できます。これにより、ミドルウェア、APIルート、.astroページ間でデータを共有できます。ユーザーデータなど、リクエスト固有のデータを各レンダリングステップをまたいで保持するために役立ちます。

localsは単一のAstroルーティング内で生成・消滅します。ルーティングされたページがレンダリングされると、localsはもう存在せず、その後また新しいものが作成されます。複数のページリクエストをまたいで保持されるべき情報は、別の場所に保存する必要があります。

`sequence()`

ミドルウェア関数を引数として受け取り、渡された順序で実行する関数です。

`createContext`

Astroミドルウェアで使用可能なAPIContextを作成するための低レベルなAPIです。

この関数は、Astroミドルウェアをプログラムから実行する目的で、インテグレーションとアダプターから使用できます。

`trySerializeLocals`

任意の値を受け取り、それをシリアライズした文字列を返す低レベルなAPIです。値をシリアライズできない場合、この関数はランタイムエラーをスローします。

GitHub Issueを作成

フィードバックを送信