fix: connect to the correct Next.js dev HMR endpoint per version (#17644)

nathanlentz · web-flow · commit 291ac661bf3a · 2026-08-05T09:27:27.000-07:00
Backport of #17632 and #17633 to `3.x`. ### What? Payload's config hot reload in development stopped working on Next.js 16.3. Adding a collection or a field had no effect until the dev server was restarted. Next.js 16.3 renamed the dev HMR WebSocket endpoint: - Old: `/_next/webpack-hmr` — [`router-server.ts#L859-L860` on `v16.2.7`](https://github.com/vercel/next.js/blob/v16.2.7/packages/next/src/server/lib/router-server.ts#L859-L860) - New: `/_next/hmr` — [`router-server.ts#L946-L947` on `v16.3.0`](https://github.com/vercel/next.js/blob/v16.3.0/packages/next/src/server/lib/router-server.ts#L946-L947) The client moved with it, in [`client/dev/hot-reloader/app/web-socket.ts`](https://github.com/vercel/next.js/blob/v16.3.0/packages/next/src/client/dev/hot-reloader/app/web-socket.ts). There is no alias in either direction: `/_next/webpack-hmr` appears only in old docs inside the 16.3.0 build, and `/_next/hmr` does not appear anywhere in 16.2.7. This branch also bumps the monorepo to Next.js 16.3.0. `3.x` was on a mix of `16.2.3` (root) and `16.2.6` (`test/`, `packages/next`). ### Why? Payload hardcoded `/_next/webpack-hmr`. On 16.3 the upgrade request no longer matched, so the socket never opened. The failure was invisible because the `onerror` handler and the surrounding `try` block both swallow errors, so `cached.reload` stayed `false` and the reload never ran. No type regeneration, no import map regeneration, and no client config cache clear. [Related Vercel PR](vercel/next.js#91415), which went into canary several months ago. ### How? Read the installed Next.js version and connect to the path that version serves: `/_next/hmr` at 16.3 and above, `/_next/webpack-hmr` below it. One socket, no configuration, correct across supported Next.js versions. ``` /_next/hmr => open /_next/webpack-hmr => no response after 8s /_next/not-a-real-path => no response after 8s ``` A wrong path never errors and never closes, so a fallback triggered by failure would hang forever on Next 16.2 and below and break HMR for every older version. `PAYLOAD_HMR_URL_OVERRIDE` keeps working and is still used verbatim, skipping version detection. ### Differences from the changes on `main` - `main` extracted a `defaultNextJsDevReloadStrategy` into `nextJsDevReloadStrategy.ts`. `3.x` has no `DevReloadStrategy` abstraction, so only the URL selection is extracted, as `getNextJsHMRURL.ts`. The socket handling stays inline in `getPayload`. - `main` sets `experimental.useTypeScriptCli: false` in both `next.config.mjs` files, because it aliases `typescript` to `@typescript/typescript6`, which ships no `tsc` bin for Next 16.3's new CLI mode to find. `3.x` uses plain `typescript@5.7.3`, so the alias problem does not exist and the setting is not needed. - `main` added `minimumReleaseAgeExclude` entries to `pnpm-workspace.yaml`. `3.x` does not set `minimumReleaseAge`. - `packages/payload` keeps `@next/env` at `^15.1.5` rather than pinning `16.3.0`, since that range also serves apps on Next 15. - Templates are unchanged, as on `main` (coming in later PR)
diff --git a/docs/troubleshooting/troubleshooting.mdx b/docs/troubleshooting/troubleshooting.mdx
@@ -157,9 +157,11 @@ This will ensure that the WebSocket connection uses the correct protocol (`wss:/
 Alternatively if more of your URL is dynamic, you can set the full URL for the WebSocket connection using the `PAYLOAD_HMR_URL_OVERRIDE` environment variable:
 
 ```
-PAYLOAD_HMR_URL_OVERRIDE=wss://localhost:3000/_next/webpack-hmr
+PAYLOAD_HMR_URL_OVERRIDE=wss://localhost:3000/_next/hmr
 ```
 
+You do not need to set this to match your Next.js version. Next.js serves HMR on `/_next/hmr` from version 16.3 onwards, and on `/_next/webpack-hmr` before that. Payload reads the installed Next.js version and connects to the correct path on its own.
+
 ## Database password encoding issues
 
 You may see some generic errors such as the following when Payload is unable to connect to your database:
diff --git a/package.json b/package.json
@@ -179,7 +179,7 @@
     "@ai-sdk/openai": "3.0.30",
     "@axe-core/playwright": "4.11.0",
     "@libsql/client": "0.14.0",
-    "@next/bundle-analyzer": "16.2.3",
+    "@next/bundle-analyzer": "16.3.0",
     "@payloadcms/db-postgres": "workspace:*",
     "@payloadcms/eslint-config": "workspace:*",
     "@payloadcms/eslint-plugin": "workspace:*",
@@ -218,7 +218,7 @@
     "lint-staged": "15.2.7",
     "minimist": "1.2.8",
     "mongoose": "8.22.1",
-    "next": "16.2.3",
+    "next": "16.3.0",
     "node-gyp": "12.2.0",
     "open": "^10.1.0",
     "p-limit": "^5.0.0",
diff --git a/packages/next/package.json b/packages/next/package.json
@@ -132,7 +132,7 @@
     "@babel/preset-env": "7.27.2",
     "@babel/preset-react": "7.27.1",
     "@babel/preset-typescript": "7.27.1",
-    "@next/eslint-plugin-next": "16.2.6",
+    "@next/eslint-plugin-next": "16.3.0",
     "@payloadcms/eslint-config": "workspace:*",
     "@types/busboy": "1.5.4",
     "@types/react": "19.2.14",
diff --git a/packages/payload/src/index.ts b/packages/payload/src/index.ts
@@ -146,6 +146,7 @@ import { fieldAffectsData, type FlattenedBlock } from './fields/config/types.js'
 import { getJobsLocalAPI } from './queues/localAPI.js'
 import { _internal_jobSystemGlobals } from './queues/utilities/getCurrentDate.js'
 import { formatAdminURL } from './utilities/formatAdminURL.js'
+import { getNextJsHMRURL } from './utilities/getNextJsHMRURL.js'
 import { isNextBuild } from './utilities/isNextBuild.js'
 import { getLogger } from './utilities/logger.js'
 import { serverInit as serverInitTelemetry } from './utilities/telemetry/events/serverInit.js'
@@ -1232,18 +1233,7 @@ export const getPayload = async (
       process.env.DISABLE_PAYLOAD_HMR !== 'true'
     ) {
       try {
-        const port = process.env.PORT || '3000'
-        const hasHTTPS =
-          process.env.USE_HTTPS === 'true' || process.argv.includes('--experimental-https')
-        const protocol = hasHTTPS ? 'wss' : 'ws'
-
-        const path = '/_next/webpack-hmr'
-        // The __NEXT_ASSET_PREFIX env variable is set for both assetPrefix and basePath (tested in Next.js 15.1.6)
-        const prefix = process.env.__NEXT_ASSET_PREFIX ?? ''
-
-        cached.ws = new WebSocket(
-          process.env.PAYLOAD_HMR_URL_OVERRIDE ?? `${protocol}://localhost:${port}${prefix}${path}`,
-        )
+        cached.ws = new WebSocket(getNextJsHMRURL())
 
         cached.ws.onmessage = (event) => {
           if (cached.reload instanceof Promise) {
diff --git a/packages/payload/src/utilities/getNextJsHMRURL.spec.ts b/packages/payload/src/utilities/getNextJsHMRURL.spec.ts
@@ -0,0 +1,80 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('./getNextVersion.js', () => ({ getNextVersion: vi.fn() }))
+
+const { getNextVersion } = await import('./getNextVersion.js')
+const { getNextJsHMRURL } = await import('./getNextJsHMRURL.js')
+
+const modernURL = 'ws://localhost:3000/_next/hmr'
+const legacyURL = 'ws://localhost:3000/_next/webpack-hmr'
+
+describe('getNextJsHMRURL', () => {
+  beforeEach(() => {
+    vi.mocked(getNextVersion).mockReturnValue('16.3.0')
+    vi.stubEnv('PAYLOAD_HMR_URL_OVERRIDE', undefined)
+    vi.stubEnv('PORT', '3000')
+  })
+
+  afterEach(() => {
+    vi.unstubAllEnvs()
+  })
+
+  it('should use the current HMR path on Next.js 16.3', () => {
+    expect(getNextJsHMRURL()).toBe(modernURL)
+  })
+
+  it('should use the current HMR path on Next.js versions above 16.3', () => {
+    vi.mocked(getNextVersion).mockReturnValue('17.0.1')
+
+    expect(getNextJsHMRURL()).toBe(modernURL)
+  })
+
+  it('should use the legacy HMR path on Next.js below 16.3', () => {
+    vi.mocked(getNextVersion).mockReturnValue('16.2.7')
+
+    expect(getNextJsHMRURL()).toBe(legacyURL)
+  })
+
+  it('should use the legacy HMR path on a Next.js 15 install', () => {
+    vi.mocked(getNextVersion).mockReturnValue('15.5.0')
+
+    expect(getNextJsHMRURL()).toBe(legacyURL)
+  })
+
+  it('should ignore pre-release identifiers when choosing the path', () => {
+    vi.mocked(getNextVersion).mockReturnValue('16.3.0-canary.12')
+
+    expect(getNextJsHMRURL()).toBe(modernURL)
+  })
+
+  it('should use the legacy HMR path on a pre-release below 16.3', () => {
+    vi.mocked(getNextVersion).mockReturnValue('16.2.0-canary.5')
+
+    expect(getNextJsHMRURL()).toBe(legacyURL)
+  })
+
+  it('should use the current HMR path when the Next.js version is unknown', () => {
+    vi.mocked(getNextVersion).mockReturnValue(undefined)
+
+    expect(getNextJsHMRURL()).toBe(modernURL)
+  })
+
+  it('should use PAYLOAD_HMR_URL_OVERRIDE whatever the version', () => {
+    vi.mocked(getNextVersion).mockReturnValue(undefined)
+    vi.stubEnv('PAYLOAD_HMR_URL_OVERRIDE', 'ws://localhost:4000/custom-hmr')
+
+    expect(getNextJsHMRURL()).toBe('ws://localhost:4000/custom-hmr')
+  })
+
+  it('should use the wss protocol when HTTPS is enabled', () => {
+    vi.stubEnv('USE_HTTPS', 'true')
+
+    expect(getNextJsHMRURL()).toBe('wss://localhost:3000/_next/hmr')
+  })
+
+  it('should include the Next.js asset prefix', () => {
+    vi.stubEnv('__NEXT_ASSET_PREFIX', '/base')
+
+    expect(getNextJsHMRURL()).toBe('ws://localhost:3000/base/_next/hmr')
+  })
+})
diff --git a/packages/payload/src/utilities/getNextJsHMRURL.ts b/packages/payload/src/utilities/getNextJsHMRURL.ts
@@ -0,0 +1,47 @@
+import { compareVersions, parseVersion } from './dependencies/versionUtils.js'
+import { getNextVersion } from './getNextVersion.js'
+
+/** Next.js serves the dev HMR WebSocket on this path from 16.3 onwards. */
+const modernHMRPath = '/_next/hmr'
+
+/** Next.js served the dev HMR WebSocket on this path before 16.3. */
+const legacyHMRPath = '/_next/webpack-hmr'
+
+const firstModernHMRPathVersion = '16.3.0'
+
+/**
+ * Builds the URL of the Next.js dev HMR WebSocket, on the path served by the
+ * installed Next.js version. `PAYLOAD_HMR_URL_OVERRIDE` is used verbatim.
+ */
+export const getNextJsHMRURL = (): string => {
+  if (process.env.PAYLOAD_HMR_URL_OVERRIDE) {
+    return process.env.PAYLOAD_HMR_URL_OVERRIDE
+  }
+
+  const port = process.env.PORT || '3000'
+  const hasHTTPS = process.env.USE_HTTPS === 'true' || process.argv.includes('--experimental-https')
+  const protocol = hasHTTPS ? 'wss' : 'ws'
+  // The __NEXT_ASSET_PREFIX env variable is set for both assetPrefix and basePath (tested in Next.js 15.1.6)
+  const prefix = process.env.__NEXT_ASSET_PREFIX ?? ''
+
+  return `${protocol}://localhost:${port}${prefix}${getHMRPath()}`
+}
+
+/**
+ * Pre-release identifiers are ignored, so that a `16.3.0-canary` build maps to the 16.3 path.
+ * An unreadable version uses the current path, as Payload being unable to resolve Next.js
+ * normally means it is not running under Next.js, where this strategy does not apply.
+ */
+const getHMRPath = (): string => {
+  const nextVersion = getNextVersion()
+
+  if (!nextVersion) {
+    return modernHMRPath
+  }
+
+  const mainVersion = parseVersion(nextVersion).parts.join('.')
+
+  return compareVersions(mainVersion, firstModernHMRPathVersion) === 'lower'
+    ? legacyHMRPath
+    : modernHMRPath
+}
diff --git a/packages/payload/src/utilities/getNextVersion.spec.ts b/packages/payload/src/utilities/getNextVersion.spec.ts
@@ -0,0 +1,19 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { getNextVersion } from './getNextVersion.js'
+
+describe('getNextVersion', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('should read the version of the installed Next.js', () => {
+    expect(getNextVersion()).toMatch(/^\d+\.\d+\.\d+/)
+  })
+
+  it('should return undefined when Next.js cannot be resolved', () => {
+    vi.spyOn(process, 'cwd').mockReturnValue('/')
+
+    expect(getNextVersion()).toBeUndefined()
+  })
+})
diff --git a/packages/payload/src/utilities/getNextVersion.ts b/packages/payload/src/utilities/getNextVersion.ts
@@ -0,0 +1,24 @@
+import { readFileSync } from 'fs'
+
+import { resolveFrom } from './dependencies/resolveFrom.js'
+
+/**
+ * Reads the version of the Next.js installed alongside the running app.
+ * Returns undefined if Next.js cannot be resolved, e.g. because Payload runs
+ * outside of Next.js or from a directory the app's dependencies are not visible from.
+ */
+export const getNextVersion = (): string | undefined => {
+  try {
+    const packageJSONPath = resolveFrom(process.cwd(), 'next/package.json', true)
+
+    if (!packageJSONPath) {
+      return undefined
+    }
+
+    const { version } = JSON.parse(readFileSync(packageJSONPath, 'utf-8'))
+
+    return typeof version === 'string' ? version : undefined
+  } catch (_) {
+    return undefined
+  }
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/test/package.json b/test/package.json
