こんにちは。 ピクシブ百科事典の開発をしております、フロントエンドエンジニアの 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つを検討しました。
- Link コンポーネントのラッパーを作る
- 良い点: 公式でも案内されている方法
- 悪い点: 触るファイルが多く影響範囲が広い
- 悪い点: リンクが踏まれなくても、
Linkとaを出し分ける計算が必要
- サーバーからフラグを渡し、
useEffectでハードリロードする- 良い点: 影響範囲が比較的狭い
- 悪い点: 2箇所の処理が連動する前提で分かりにくい
- 悪い点: SPA 遷移時のリクエストまでは走るので、その分の API 呼び出しが無駄になる
router.events.on("routeChangeStart")を使う- 良い点: 既存の実装がそのまま使える
- 悪い点: 遷移をブロックできない場合がある
- middleware でリダイレクトさせる
- 良い点: 1ファイル触るだけで済む
- 良い点: 記事名の一部が URL として扱われてしまう問題(後述)も解決できる
- 悪い点: 社内で誰も試した人がいなかった
1. Link コンポーネントのラッパーを作る
先ほど少し紹介した、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 のソースコードも確認してみてください。
- https://github.com/vercel/next.js/blob/v15.5.20/packages/next/src/server/web/adapter.ts#L445-L457
- https://github.com/vercel/next.js/blob/v15.5.20/packages/next/src/shared/lib/router/router.ts#L295-L311
重要なのは 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 遷移に悩んでいる方の一助になれば幸いです!