# OpenNextのPages Routerで依存パッケージの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](https://github.com/opennextjs/opennextjs-cloudflare/blob/%40opennextjs/cloudflare%401.20.17/packages/cloudflare/src/cli/build/patches/plugins/pages-router-context.ts) にもこの分岐は存在する。
  - パッチはアダプタのバージョンを指定して登録するので、アダプタの更新のたびに再作成する。

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

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

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

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

Next.jsは2つを同一のインスタンスに統一する。
バンドルするコードでは [ビルドで`.shared-runtime`のimportをvendoredのモジュールに置換する](https://github.com/vercel/next.js/blob/v16.2.11/packages/next/src/build/webpack-config.ts#L1989)。

Pages Routerは [デフォルトではサーバーの依存パッケージをバンドルしない](https://nextjs.org/docs/pages/api-reference/config/next-config-js/bundlePagesRouterDependencies) ので、依存は実行時に`node_modules`から`require`される（external）。

externalの依存にも同じ置換が必要で、Node.jsでは [`require`を上書きするrequire-hookがこの置換を実施する](https://github.com/vercel/next.js/blob/v16.2.11/packages/next/src/server/require-hook.ts#L74-L84)。

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

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

アダプタは [require-hookを空のモジュールに置換する](https://github.com/opennextjs/opennextjs-cloudflare/blob/%40opennextjs/cloudflare%401.20.17/packages/cloudflare/src/cli/build/patches/plugins/require-hook.ts)。
代わりに [`pages-router-context`というesbuildのプラグイン](https://github.com/opennextjs/opennextjs-cloudflare/blob/%40opennextjs/cloudflare%401.20.17/packages/cloudflare/src/cli/build/patches/plugins/pages-router-context.ts) が、バンドルの中でrequire-hookと同様の置換を実施する。
このプラグインは [コンテキストの参照先を統一するために追加された](https://github.com/opennextjs/opennextjs-cloudflare/pull/607)。

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

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

対象はWorkerが実行時にレンダリングするページである。
getServerSidePropsのページのほか、ビルド時に未生成のパスを初回のリクエスト時に生成するページでも [依存パッケージのタグは欠落しうる](https://github.com/opennextjs/opennextjs-cloudflare/issues/1389)。
ビルド時のHTMLをそのまま配信するページは対象外である。

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

```js
// 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" }));
};
```

```tsx
// 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種類のタグで判別する。

```bash
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以降では置換の登録を省略する。

```js
// @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 に置換する
    });
},
```

```mermaid
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系でもある](https://github.com/opennextjs/opennextjs-cloudflare/issues/1389) 。

バージョンの分岐を削除して置換を常に有効にする [修正](https://github.com/opennextjs/opennextjs-cloudflare/pull/1440) は、2026年11月時点ではマージされていない。

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

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

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

```bash
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`が登録される。

```js
// 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,
                    });
                }
            });
        },
    };
}
```

```yaml
# pnpm-workspace.yaml
patchedDependencies:
  "@opennextjs/cloudflare@<version>": patches/@opennextjs__cloudflare@<version>.patch
```

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

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

### パッチ以外の対処の制約

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