entry-header-eye-catch.html
entry-title-container.html

entry-header-author-info.html
Article by

Next.js の SPA 遷移を middleware で無効化する

こんにちは。 ピクシブ百科事典の開発をしております、フロントエンドエンジニアの ahu です。

ピクシブ百科事典(以下、百科事典と呼びます)は、「みんなでつくる百科事典」を合言葉に運営されている、オンライン百科事典サービスです。 百科事典では現在、従来の PHP による表示から Next.js への段階的移行を進めており、2つの異なるアーキテクチャが同居する形になっています。 こうした移行中の状態では、Next.js の SPA 遷移がかえって邪魔になることがあり、pixiv 本体でも大規模な対応コードを入れた事例があります。

今回は、そんな SPA 遷移を条件分岐で無効化する仕組みを、Next.js の middleware の変更だけで実現した例を紹介します。 百科事典特有の、記事名の一部が URL として扱われてしまう問題も、この仕組みで解決しているのでぜひ読んでみてください!

SPA 遷移で困ること

まず最初に、Next.js と別のアーキテクチャが同居している場合、SPA 遷移がどのような問題を起こすのか見ていきましょう。 pixiv 本体や百科事典では、以下のようなアーキテクチャを採用しています。

  • 既存の Smarty(PHP のテンプレートエンジン)製のページと、Next.js 製のページが同居している
  • Smarty のページを Next.js へ移行する間は、Feature Flag のような仕組みで開発中のページへのアクセスを制限している
  • この Feature Flag を見て、Smarty のページを表示するか Next.js のサーバーに処理を委譲するかを決めるのは、PHP 側のルーター

つまり、フラグ制御のあるページを正しく表示するには、必ず PHP 側のルーターを通る必要があるわけです。 しかし SPA 遷移では、ページの切り替えがフロントエンドで完結するため、処理が PHP 側まで届きません。 すると、本来ルーターで弾かれる想定のユーザーが開発中のページにアクセスできてしまったり、それを防ぐためのコードでブラウザバックの遷移先が壊れる、という問題が発生します。

後述するように、一般的には Next.js の Link を素の a タグに置換すれば、処理が PHP 側に届くようになり意図通りの挙動になります。 しかしこの方法では、リンクごとに Link と a を出し分ける計算が必要で、すべてのリンクをラッパーコンポーネントで置換する必要もあるため、影響範囲が大きくなります。

考えられる選択肢とその比較

ここからは、実際に検討した解決策を紹介・比較します。 無駄のなさ・変更量の少なさ・確実性などの観点から、次の4つを検討しました。

  1. Link コンポーネントのラッパーを作る
    • 良い点: 公式でも案内されている方法
    • 悪い点: 触るファイルが多く影響範囲が広い
    • 悪い点: リンクが踏まれなくても、Link と a を出し分ける計算が必要
  2. サーバーからフラグを渡し、useEffect でハードリロードする
    • 良い点: 影響範囲が比較的狭い
    • 悪い点: 2箇所の処理が連動する前提で分かりにくい
    • 悪い点: SPA 遷移時のリクエストまでは走るので、その分の API 呼び出しが無駄になる
  3. router.events.on("routeChangeStart") を使う
    • 良い点: 既存の実装がそのまま使える
    • 悪い点: 遷移をブロックできない場合がある
  4. middleware でリダイレクトさせる
    • 良い点: 1ファイル触るだけで済む
    • 良い点: 記事名の一部が URL として扱われてしまう問題(後述)も解決できる
    • 悪い点: 社内で誰も試した人がいなかった

先ほど少し紹介した、Link を素の a タグに置換する方法です。 Link をラップしたコンポーネントを用意し、props で渡される遷移先に応じて Link か a タグかを出し分けます。 Link は、SPA 遷移させる機能を持つ Next.js のコンポーネントで、これを部分的に差し替えることで SPA 遷移を防ぐわけです。 Next.js の 公式ドキュメント でも、React Context と併用してラッパーを運用する方法が案内されています。

しかしこの方法は、サービス内のすべてのリンクをラッパーコンポーネントで置換する必要があり、コードの変更量やレビュー量が多くなる懸念があります。 また実際には踏まれなかったリンクについても、Link と a を出し分ける計算は必要で、百科事典のように相互リンクが多いサービスでは計算が無駄になりやすいです。

2. サーバーからフラグを渡し、useEffect でハードリロードする

getServerSideProps には Feature Flag が渡ってくるので、それを props 経由でクライアントに渡し、遷移をブロックすべきページでは useEffect でハードリロードする方法です。 ブロックしたい対象のページにだけ手を入れればよく、影響範囲を比較的小さくできる利点があります。

ただしこの方法は、サーバー側とクライアント側の2箇所の処理の連動が前提なため、処理の流れが追いにくい問題があります。 また結果的に遷移をブロックする場合でも、SPA 遷移時のリクエストまでは走っているので、そのリクエストが直後のリロードで無駄になってしまいます。

3. router.events.on("routeChangeStart") を使う

routeChangeStart は、Next.js の Pages Router で使える、ページ遷移の開始を意味するイベントです。 実は以前の百科事典には、この routeChangeStart イベントで SPA 遷移をブロックする実装がありました。

しかし routeChangeStart は、非同期的な API でブラウザの遷移自体を待たせられるわけではありません。 そのため、ブラウザの遷移が先に完了してしまうと、リロードが間に合わず遷移をブロックできないことがありました。 このような確率的すり抜けが起きうるため、今回は確実性の観点から採用を見送ることになりました。

4. middleware でリダイレクトさせる

Next.js には middleware という仕組みがあり、ページのルーティングの前にサーバーサイドで共通の処理が挟めます。 SPA 遷移でも必ず middleware は通るため、必要な場合に手動でリダイレクトをすれば、処理が PHP 側まで届くようになります。 この方法であれば、これまで挙げてきた懸念点を解消しつつ、特殊な遷移を一元管理することまでできそうです。

  • 触るファイルは1つだけ。1 のように影響範囲が大きくならない
  • 実際に遷移が始まる直前に計算できる。1 のように計算が無駄にならない
  • 実際に遷移が始まる前にブロックできる。2 のようにリクエストが無駄にならず、3 のようにすり抜けることもない
  • 「このページはこの条件の場合だけ特殊な遷移をさせる」を一元管理でき、見通しが良い

また百科事典には、記事名の一部が URL として扱われてしまう問題(後述)がありましたが、遷移先の計算に記事名の正規化も盛り込めば、これも同時に解決できそうです。 以上の理由から、今回は選択肢 4 の middleware を使う方法を採用しました。

具体的な実装の紹介

ここからは、具体的な実装を見ていきましょう。 middleware の本体は、次のような構造になっています。 SPA 遷移かつリダイレクトすべき条件の場合だけ、リダイレクト用のレスポンスを作って返します。

import { type NextRequest, NextResponse } from "next/server";

export default function middleware(req: NextRequest) {
  const isSpaRequest = req.headers.has("x-nextjs-data");
  const { pathname, searchParams, locale, defaultLocale } = req.nextUrl;

  const redirectAction =
    isSpaRequest && spaRedirectActions(pathname, searchParams);
  if (redirectAction) {
    /**
     * data request に対して NextResponse.redirect() を使うと、
     * x-nextjs-redirect が相対パスに設定される。
     * router は x-nextjs-redirect が相対パスだと、
     * 内部リダイレクトとして処理されるためリダイレクトの無限ループが起きる。
     * x-nextjs-redirect に絶対 URL を指定した NextResponse を返すことで、
     * 強制的に hard navigation させる。
     */
    const hostname = req.headers.get("x-forwarded-host")!;
    const localePrefix = locale === defaultLocale ? "" : `/${locale}`;
    const destination = `https://${hostname}${localePrefix}${redirectAction}`;
    return new NextResponse(null, {
      headers: { "x-nextjs-redirect": destination },
    });
  }

  // ... 記事名のエンコードや末尾スラッシュの除去など(後述)

  return NextResponse.next();
}

export const config = {
  matcher: ["/((?!_next/static).*)"],
};

ポイントは、SPA 遷移かどうかを x-nextjs-data ヘッダの有無で判定している点です。 このヘッダが付いているリクエストは Next.js のデータリクエスト、つまり SPA 遷移です。 x-nextjs-redirect 関連の挙動については、Next.js のソースコードも確認してみてください。

重要なのは spaRedirectActions() という関数で、ここで「このページはこの条件の場合だけ特殊な遷移をさせる」を一元管理しています。 リダイレクトするなら遷移先の pathname 以降を返し、しないなら false を返す設計です。 ヘッダなどを経由して、ここでも Feature Flag が確認できるようになれば、カナリアリリースに対応させることも可能です。

/**
 * SPA 遷移をブロックして PHP 側にリダイレクトしたい場合の条件を全部ここに書く
 */
const spaRedirectActions = (
  pathname: string,
  searchParams: URLSearchParams,
): string | false => {
  const params = new URLSearchParams(searchParams);

  // パスに記事名が含まれる場合に使える、標準的な動作の定義
  const defaultAction = (params: URLSearchParams): string => {
    const destinationPathname =
      encodeTagNameInPath(pathname, searchParams) || pathname;
    params.delete("tagName");
    const destinationParams = params.size > 0 ? `?${params}` : "";
    return `${destinationPathname}${destinationParams}`;
  };

  // これより下に分岐を追加していく
  if (pathname.startsWith("/ae/")) {
    return defaultAction(params);
  }

  // リダイレクトをしない
  return false;
};

spaRedirectActions に if 文を並べる形にしたことで、条件の記述の自由度を確保しつつ、リダイレクト対象のパスを1箇所にまとめられるようにしています。 また spaRedirectActions を middleware の外に定義することで、この関数の意味さえ知っていればリダイレクトが実装でき、初学者に優しい実装になりました。

記事名の一部が URL として扱われてしまう問題

百科事典は、ユーザーが自由に記事を作れて、その記事名がそのまま URL の一部になるサービスです。 そのため Fate/staynight や .hack// のように、記事名に URL の区切り文字が含まれる場合には、Next.js の URL の正規化処理などで遷移先がおかしくなることがありました。

こうした挙動を直すため、選択肢 2 や 3 のようなコードが対症療法的に様々な箇所で導入されており、ページ遷移の特殊対応自体がかなり複雑化していました。 今回それらを spaRedirectActions に一本化し、既存の複雑な実装をシンプルな仕組みに移行できたことは、今後の保守性の面でも大きな収穫だったと思います。

また middleware の処理は何度も呼び出されるため、記事名の正規化では可能なケースで変換を省くなど、無駄な処理を減らす工夫も積極的に取り入れています。 この記事名の正規化を担うのが、spaRedirectActions の defaultAction で呼んでいた、encodeTagNameInPath という関数です。 この関数も、spaRedirectActions と同じように、string | false を返す設計になっています。

/**
 * 記事名が含まれる pathname に対して、
 * 記事名をエンコードした pathname を返すための補助関数
 *
 * 例:
 * - /a/Fate/staynight → / で区切らず Fate/staynight を記事名として扱う
 * - /history/.hack///diff → /diff の直前の .hack// までを記事名として扱う
 *
 * 記事名を含まない pathname に対しては false を返す
 */
export const encodeTagNameInPath = (
  pathname: string,
  searchParams: URLSearchParams,
): string | false => {
  // ...
};

おわりに

以上、Next.js の段階的移行で問題になる SPA 遷移を、middleware だけで無効化する方法を紹介しました。 結果として、SPA 遷移の制御と記事名の正規化という2つの難題を、spaRedirectActions の仕組みでまとめて解消できました。

段階的移行の途中では、SPA 遷移をキャンセルしたい場面がどうしても出てくると思います。 そんなとき、リンクをすべて置き換える以外の方法として、middleware だけで遷移を制御するという発想は、影響範囲を最小限に抑えられる有力な選択肢になるでしょう。 対症療法的に散らばっていた特殊対応を1箇所にまとめられたことで、現状の把握やバグが起きたときの調査も、ぐっと楽になりました。

この記事が、Next.js への段階的移行で SPA 遷移に悩んでいる方の一助になれば幸いです!

icon
ahu
フロントエンドエンジニアとして2021年に新卒入社。 ゲームとプログラミングが好き。