本文へスキップ
0 views

OpenNextのPages Routerで依存パッケージのheadタグ欠落を修正する

opennext-pages-router-next-head

サマリ

  • OpenNextでCloudflare Workersが実行時にレンダリングするPages Routerのページでは、依存パッケージのheadタグがサーバーのHTMLから欠落しうる。
    • Next.jsがバンドルせずnode_modulesから読み込む依存パッケージが、next/headで出力するタグが対象になる。
    • 同じページでもアプリのコードのnext/headのタグは出力される。
    • ブラウザの表示だけではサーバーのHTMLでの欠落を判別できないので、サーバーのHTMLで確認する。
  • 原因は依存のnext/headとNext.jsのレンダラーが、タグを受け渡すReactのコンテキストHeadManagerContextの別々のインスタンスを参照することにある。
    • Node.jsではNext.jsが参照先を統一する。
    • Next.js 15.3以降で置換を省略するOpenNextのアダプタでは、この統一が実施されない。
  • アダプタのpages-router-context.jsから、Next.js 15.3以降で処理を省略する分岐をpnpm patchで削除すると、この省略で欠落していた依存のタグも出力される。
    • アダプタ1.20.17 にもこの分岐は存在する。
    • パッチはアダプタのバージョンを指定して登録するので、アダプタの更新のたびに再作成する。

前提となるコンテキストの参照先の統一

next/headとレンダラーが読み込むコンテキスト

Pages Routerのnext/headは、値を共有するReactのコンテキストHeadManagerContextを通じて、タグをレンダラーに通知する。
レンダラーはこのコンテキストに値を提供し、通知されたタグを<head>に出力する。

next/headの実装 は、コンテキストをhead-manager-context.shared-runtimeというモジュールから読み込む。
レンダラーはこのコンテキストを、Next.jsのランタイムに同梱されたvendored/contexts/head-manager-contextから読み込む。
next/headが読み込んだコンテキストと、レンダラーが値を提供したコンテキストのインスタンスが異なると、next/headはその値を取得できず、タグはHTMLに出力されない。

Next.jsは2つを同一のインスタンスに統一する。
バンドルするコードでは ビルドで.shared-runtimeのimportをvendoredのモジュールに置換する。

Pages Routerは デフォルトではサーバーの依存パッケージをバンドルしない ので、依存は実行時にnode_modulesからrequireされる(external)。

externalの依存にも同じ置換が必要で、Node.jsでは requireを上書きするrequire-hookがこの置換を実施する。

OpenNextのアダプタによるimportの置換

OpenNextの Cloudflare向けアダプタ は@opennextjs/cloudflareである。
アダプタはNext.jsのサーバーのコードとnode_modulesをesbuildでWorkerのバンドルに変換する。

アダプタは require-hookを空のモジュールに置換する。
代わりに pages-router-contextというesbuildのプラグイン が、バンドルの中でrequire-hookと同様の置換を実施する。
このプラグインは コンテキストの参照先を統一するために追加された。

依存パッケージのタグだけがサーバーのHTMLから欠落する

依存パッケージのheadタグが欠落するページの例

対象はWorkerが実行時にレンダリングするページである。
getServerSidePropsのページのほか、ビルド時に未生成のパスを初回のリクエスト時に生成するページでも 依存パッケージのタグは欠落しうる。
ビルド時のHTMLをそのまま配信するページは対象外である。

次のexternal-headは、next/headをrequireして<Head>を返却するCommonJSモジュールである。

// node_modules/external-head/index.cjs
const React = require("react");
const mod = require("next/head");
const Head = mod.default || mod;
const h = React.createElement;
module.exports = function ExternalHead() {
  return h(Head, null,
    h("title", null, "SSR dep head"),
    h("meta", { name: "description", content: "ssr-dep-desc" }),
    h("link", { rel: "canonical", href: "https://example.com/ssr-dep" }));
};
// pages/ssr-dep.tsx
const ExternalHead = require("external-head");
export const getServerSideProps = async () => ({ props: {} });
export default function SSRDep() {
  return <><ExternalHead /><main>SSR dependency body</main></>;
}

このページをWorkerで実行すると、15.3以降で置換を省略するアダプタでは、サーバーのHTMLからtitle、description、canonicalが欠落しうる。
アダプタの分岐を削除すると、external-headとレンダラーは同じインスタンスを参照し、3種類のタグが出力される。

サーバーのHTMLでのタグの欠落の判別

ブラウザの開発者ツールのElementsが示す現在のDOMは、ハイドレーション(ReactがサーバーのHTMLを引き継ぐ処理)の後にはサーバーのHTMLと異なる場合がある。
欠落はcurlで取得したHTMLの<head>の3種類のタグで判別する。

url="https://<host>/<page>"
html="$(curl -sS --fail "$url")" || { echo "取得に失敗: $url"; exit 1; }
head="$(tr -d '\n' <<<"$html" | grep -oE '<head[ >].*</head>')"
for pattern in '<title' 'name="description"' 'rel="canonical"'; do
  if grep -q "$pattern" <<<"$head"; then echo "あり: $pattern"; else echo "なし: $pattern"; fi
done

次の2つに該当する場合は依存のnext/headとレンダラーが別のHeadManagerContextを参照していないかを調査する。

  • 1つのページ内で、アプリのコードのタグは出力されるのに、依存のタグは欠落する。
  • next startで起動したNode.js側では、require-hookが参照先を統一するので、この欠落は発生しない。

依存はアダプタが置換しない別のコンテキストを参照する

アダプタ1.20.17のpages-router-context.jsは、Next.js 15.3以降では置換の登録を省略する。

// @opennextjs/cloudflare 1.20.17 の dist/cli/build/patches/plugins/pages-router-context.js
setup: (build) => {
    // If we are after 15.3, we don't need to patch the context anymore
    if (isAfter153) {
        return;
    }
    build.onResolve({ filter: /.*shared-runtime/ }, async ({ path, resolveDir, ...options }) => {
        // next/dist/server/route-modules/pages/vendored/contexts/<name>.js に置換する
    });
},
sequenceDiagram participant D as 依存パッケージのnext/head participant S as shared-runtimeのコンテキスト participant V as vendoredのコンテキスト participant R as レンダラー alt next start(Node.js) Note over D,V: require-hookがshared-runtimeの読み込みをvendoredに置換する D->>V: コンテキストを通じてレンダラーにタグを通知する R-->>R: タグをheadに出力する else Worker(アダプタ無変更、Next.js 15.3以降) Note over D,S: require-hookは空、pages-router-contextは置換しない D->>S: 別のコンテキストを参照する Note over S,R: レンダラーが提供する値を取得できず、タグは出力されない else Worker(分岐を削除) Note over D,V: pages-router-contextがesbuildのビルドで置換する D->>V: コンテキストを通じてレンダラーにタグを通知する R-->>R: タグをheadに出力する end

依存のパッケージが出力するタグの欠落の 報告はアダプタ1.20系でもある 。

バージョンの分岐を削除して置換を常に有効にする 修正 は、2026年11月時点ではマージされていない。

アダプタのパッチでコンテキストの置換を常に有効にする

アダプタを1.20.17に固定した場合、distのpages-router-context.jsからisAfter153の分岐を削除する。

pnpm 7.4以降では pnpm patch でパッチのファイルを作成し、patchedDependenciesに登録する。
登録先は現行のpnpmではpnpm-workspace.yamlで、従来のバージョンではpackage.jsonのpnpm.patchedDependenciesである。

pnpm patch @opennextjs/cloudflare@<version>
# 表示された一時ディレクトリの dist/cli/build/patches/plugins/pages-router-context.js を編集する
pnpm patch-commit <表示された一時ディレクトリ>

pnpm patchの一時ディレクトリで、isAfter153の定義の1行と分岐の4行を削除し、ほかの行は変更しない。
次の削除後のコードではNext.js 15.3以降でもbuild.onResolveが登録される。

// dist/cli/build/patches/plugins/pages-router-context.js(削除後)
export function patchPagesRouterContext(buildOpts) {
    const pathRegex = /^.*\/(?<CONTEXT>.*)\.shared-runtime$/;
    const isAfter15 = compareSemver(buildOpts.nextVersion, ">=", "15.0.0");
    const basePath = `next/dist/server/${isAfter15 ? "" : "future/"}route-modules/pages/vendored/contexts/`;
    return {
        name: "pages-router-context",
        setup: (build) => {
            build.onResolve({ filter: /.*shared-runtime/ }, async ({ path, resolveDir, ...options }) => {
                const match = path.match(pathRegex);
                if (match && match.groups?.CONTEXT) {
                    const newPath = `${basePath}${match.groups.CONTEXT}.js`;
                    return await build.resolve(newPath, {
                        resolveDir,
                        ...options,
                    });
                }
            });
        },
    };
}
# pnpm-workspace.yaml
patchedDependencies:
  "@opennextjs/cloudflare@<version>": patches/@opennextjs__cloudflare@<version>.patch

キーにアダプタのバージョンが含まれるので、アダプタを更新したら更新後のバージョンでパッチを再作成し、キーとファイル名を変更する。
未使用のパッチを許可しない設定 allowUnusedPatches: falseでは、キーを変更しないままアダプタを更新すると、未使用のパッチがあるため、pnpm installがエラーになる。

パッチを再作成した後はwrangler devでWorkerを起動し、判別の節のcurlで、依存がタグを出力するページの3種類のタグを確認する。

パッチ以外の対処の制約

  • 上の分岐はバンドラーを判定しないので、Cloudflare向けのビルドだけnext build --webpackにしても、置換は省略されたままになる。
  • 依存を使用せず、タグを全てアプリのコードのnext/headで出力しても、next/headを使用する依存を追加した時点で同じ欠落が発生しうる。
  • 修正のプルリクエストのマージまで対処を保留すると、その間、該当するページの依存のheadタグは欠落しうる。

この記事に出てくる用語

用語集の一覧へ

関連事例

  • セキュリティ診断・対策

    事例:新サービス公開前のセキュリティ診断と修正

    不動産の分野で事業を拡大する会社は、新サービスを公開する前に、悪用されうる脆弱性を解消できました。診断の結果を根拠に取引先へ安全を説明できる状態で、新サービスを公開しています。診断は開発支援会社の KDOT が担当し、修正はサイトによって KDOT と各サイトの開発会社が分担しました。

  • データ分析支援

    事例:過去実績を提案に活用する分析の仕組み

    広告代理店との取り組みです。同社は過去実績の示唆を次の提案へ反映し、結果をどのように予測したか、その背景まで提案先のクライアントへ説明できるようになりました。KDOT は案ごとの見込みと判断材料を比較できる仕組みを業務アプリとして実装しました。さらに業務アプリの中核となる処理ロジックと機械学習モデルについて、特許手続きを担う弁理士が技術の新規性や工夫を検討するための資料を作成しました。その後この発明には特許が付与されました。

お問い合わせ・ご相談

システム開発、データ活用、プロダクトづくりのことならお気軽にご相談ください。要件が固まる前の整理や、お見積もりだけのご依頼も承ります。