fix(next): fix hmr, bump minimum required next.js 16 version to 16.2.2 (#16202)

Next.js <16.2.2 requires the `--no-server-fast-refresh` flag appended to
the `next dev` command in order for HMR to work. In 16.2.2, we can now
set `experimental.enableServerFastRefresh` to disable server fast
refresh, which fixes HMR for all users, without requiring a new flag.

This PR:
- bumps the minimum required Next.js 16 version to 16.2.2
- sets `experimental.enableServerFastRefresh` if Next.js >=16.2.2 is
detected
- bumps Next.js to 16.2.2 in our monorepo and all templates
- logs a console warning for all users using Next.js 16 - 16.2.1

After release, we'll remove the `--no-server-fast-refresh` flag from our
templates in a separate PR. We cannot do it in this PR, as a newer
Payload version is required

---
- To see the specific tasks where the Asana app for GitHub is being
used, see below:
  - https://app.asana.com/0/0/1213971891044433

Author: AlessioGr

docs/getting-started/installation.mdx

@@ -16,7 +16,7 @@ Payload requires the following software:
   - `15.2.9` - `15.2.x`
   - `15.3.9` - `15.3.x`
   - `15.4.11` - `15.4.x`
-  - `16.2.0`+
+  - `16.2.2`+
 - Any [compatible database](/docs/database/overview) (MongoDB, Postgres or SQLite)
 
 <Banner type="warning">
@@ -25,17 +25,6 @@ Payload requires the following software:
   sure you're using one of the supported version ranges listed above.
 </Banner>
 
-<Banner type="warning">
-  **Next.js 16.2+:** Server fast refresh (enabled by default) breaks Payload HMR - config changes won't propagate until a full server restart. Add `--no-server-fast-refresh` to your dev command as a workaround:
-
-```bash
-next dev --no-server-fast-refresh
-```
-
-This is a temporary workaround until the upstream issue is resolved.
-
-</Banner>
-
 <Banner type="info">
   **Cache Components:** While Next.js `cacheComponents` can be enabled alongside
   Payload without causing errors in the admin panel, full compatibility is not

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.1",
+    "@next/bundle-analyzer": "16.2.2",
     "@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.15.1",
-    "next": "16.2.1",
+    "next": "16.2.2",
     "node-gyp": "12.2.0",
     "open": "^10.1.0",
     "p-limit": "^5.0.0",

packages/next/package.json

@@ -131,7 +131,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.1",
+    "@next/eslint-plugin-next": "16.2.2",
     "@payloadcms/eslint-config": "workspace:*",
     "@types/busboy": "1.5.4",
     "@types/react": "19.2.9",
@@ -145,7 +145,7 @@
   },
   "peerDependencies": {
     "graphql": "^16.8.1",
-    "next": ">=15.2.9 <15.3.0 || >=15.3.9 <15.4.0 || >=15.4.11 <15.5.0 || >=16.2.0-canary.10 <17.0.0",
+    "next": ">=15.2.9 <15.3.0 || >=15.3.9 <15.4.0 || >=15.4.11 <15.5.0 || >=16.2.2 <17.0.0",
     "payload": "workspace:*"
   },
   "engines": {

packages/next/src/withPayload/withPayload.js

@@ -6,6 +6,7 @@
  */
 import {
   getNextjsVersion,
+  supportsServerFastRefreshConfig,
   supportsTurbopackExternalizeTransitiveDependencies,
 } from './withPayload.utils.js'
 import { withPayloadLegacy } from './withPayloadLegacy.js'
@@ -24,12 +25,13 @@ export const withPayload = (nextConfig = {}, options = {}) => {
   const nextjsVersion = getNextjsVersion()
 
   const supportsTurbopackBuild = supportsTurbopackExternalizeTransitiveDependencies(nextjsVersion)
+  const hasServerFastRefreshConfigOption = supportsServerFastRefreshConfig(nextjsVersion)
 
   const env = nextConfig.env || {}
 
   if (nextConfig.experimental?.staleTimes?.dynamic) {
     console.warn(
-      'Payload detected a non-zero value for the `staleTimes.dynamic` option in your Next.js config. This will slow down page transitions and may cause stale data to load within the Admin panel. To clear this warning, remove the `staleTimes.dynamic` option from your Next.js config or set it to 0. In the future, Next.js may support scoping this option to specific routes.',
+      'Payload: detected a non-zero value for the `staleTimes.dynamic` option in your Next.js config. This will slow down page transitions and may cause stale data to load within the Admin panel. To clear this warning, remove the `staleTimes.dynamic` option from your Next.js config or set it to 0. In the future, Next.js may support scoping this option to specific routes.',
     )
     env.NEXT_PUBLIC_ENABLE_ROUTER_CACHE_REFRESH = 'true'
   }
@@ -38,6 +40,12 @@ export const withPayload = (nextConfig = {}, options = {}) => {
     env.PAYLOAD_CACHE_COMPONENTS_ENABLED = 'true'
   }
 
+  if (nextjsVersion?.major === 16 && !hasServerFastRefreshConfigOption) {
+    console.warn(
+      'Payload: You are using an unsupported Next.js 16 version. You can find the supported Next.js versions here: https://payloadcms.com/docs/getting-started/installation',
+    )
+  }
+
   const consoleWarn = console.warn
 
   const sassWarningTexts = [
@@ -61,6 +69,11 @@ export const withPayload = (nextConfig = {}, options = {}) => {
   const baseConfig = {
     ...nextConfig,
     env,
+    experimental: {
+      ...(nextConfig.experimental || {}),
+      // Server fast refresh breaks HMR
+      ...(hasServerFastRefreshConfigOption ? { enableServerFastRefresh: false } : {}),
+    },
     sassOptions: {
       ...(nextConfig.sassOptions || {}),
       /**

packages/next/src/withPayload/withPayload.utils.js

@@ -106,6 +106,39 @@ export function getNextjsVersion() {
   }
 }
 
+/**
+ * Checks if the current Next.js version supports the `experimental.serverFastRefresh` option.
+ * This was introduced in Next.js v16.2.2
+ * @param {SemVer | undefined} version
+ * @returns {boolean}
+ */
+export function supportsServerFastRefreshConfig(version) {
+  if (!version) {
+    return false
+  }
+
+  const { major, minor, patch } = version
+
+  if (major === undefined || minor === undefined || patch === undefined) {
+    return false
+  }
+
+  if (major > 16) {
+    return true
+  }
+
+  if (major === 16) {
+    if (minor > 2) {
+      return true
+    }
+    if (minor === 2) {
+      return patch >= 2
+    }
+  }
+
+  return false
+}
+
 /**
  * Checks if the current Next.js version supports Turbopack externalize transitive dependencies.
  * This was introduced in Next.js v16.1.0-canary.3

packages/next/src/withPayload/withPayloadLegacy.js

@@ -47,7 +47,7 @@ export const withPayloadLegacy = (nextConfig = {}) => {
 
   if (isBuild && (isTurbopackNextjs15 || isTurbopackNextjs16)) {
     throw new Error(
-      'Your Next.js version does not support using Turbopack for production builds. The *minimum* Next.js version required for Turbopack Builds is 16.1.0. Please upgrade to the latest supported Next.js version to resolve this error.',
+      'Payload: Your Next.js version does not support using Turbopack for production builds. The *minimum* Next.js version required for Turbopack Builds is 16.1.0. Please upgrade to the latest supported Next.js version to resolve this error.',
     )
   }
 

packages/ui/package.json

@@ -178,7 +178,7 @@
     "payload": "workspace:*"
   },
   "peerDependencies": {
-    "next": ">=15.2.9 <15.3.0 || >=15.3.9 <15.4.0 || >=15.4.11 <15.5.0 || >=16.2.0-canary.10 <17.0.0",
+    "next": ">=15.2.9 <15.3.0 || >=15.3.9 <15.4.0 || >=15.4.11 <15.5.0 || >=16.2.2 <17.0.0",
     "payload": "workspace:*",
     "react": "^19.0.1 || ^19.1.2 || ^19.2.1",
     "react-dom": "^19.0.1 || ^19.1.2 || ^19.2.1"