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

サマリ
- OpenNextでCloudflare Workersが実行時にレンダリングするPages Routerのページでは、依存パッケージのheadタグがサーバーの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 に置換する
});
},
依存のパッケージが出力するタグの欠落の 報告はアダプタ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タグは欠落しうる。


