fix: ensure importMap is reliably generated during HMR (fixes Next.js 16 issue) (#14474)

Fixes #14419

## Problem

Next.js 16 changes the order of `getPayload()` calls during HMR. In
testing, the frontend now calls `getPayload()` before the admin panel
does. Since the frontend typically has `skipImportMapGeneration: true`
(due to no importMap passed to `getPayload`), this was skipping import
map generation entirely, breaking the admin panel.

## Solution

This PR ensures the import map is always regenerated during HMR by
passing `false` as the second parameter to `reload()`, regardless of the
`options.importMap` value passed to `getPayload()`.

Additionally, a new `ignoreResolveError` option is added to handle cases
where `getPayload()` is called exclusively from the frontend (where no
import map file exists). This prevents errors from interrupting the HMR
process in frontend-only scenarios.

Author: AlessioGr

packages/payload/src/bin/generateImportMap/index.ts

@@ -42,7 +42,14 @@ export type AddToImportMap = (payloadComponent?: PayloadComponent | PayloadCompo
 
 export async function generateImportMap(
   config: SanitizedConfig,
-  options?: { force?: boolean; log: boolean },
+  options?: {
+    force?: boolean /**
+     * If true, will not throw an error if the import map file path cannot be resolved
+    Instead, it will return silently.
+     */
+    ignoreResolveError?: boolean
+    log: boolean
+  },
 ): Promise<void> {
   const shouldLog = options?.log ?? true
 
@@ -64,6 +71,14 @@ export async function generateImportMap(
     rootDir,
   })
 
+  if (importMapFilePath instanceof Error) {
+    if (options?.ignoreResolveError) {
+      return
+    } else {
+      throw importMapFilePath
+    }
+  }
+
   const importMapToBaseDirPath = getImportMapToBaseDirPath({
     baseDir,
     importMapPath: importMapFilePath,

packages/payload/src/bin/generateImportMap/utilities/resolveImportMapFilePath.ts

@@ -21,15 +21,15 @@ export async function resolveImportMapFilePath({
   adminRoute?: string
   importMapFile?: string
   rootDir: string
-}) {
+}): Promise<Error | string> {
   let importMapFilePath: string | undefined = undefined
 
   if (importMapFile?.length) {
     if (!(await pathOrFileExists(importMapFile))) {
       try {
         await fs.writeFile(importMapFile, '', { flag: 'wx' })
       } catch (err) {
-        throw new Error(
+        return new Error(
           `Could not find the import map file at ${importMapFile}${err instanceof Error && err?.message ? `: ${err.message}` : ''}`,
         )
       }
@@ -50,7 +50,7 @@ export async function resolveImportMapFilePath({
         await fs.writeFile(importMapFilePath, '', { flag: 'wx' })
       }
     } else {
-      throw new Error(
+      return new Error(
         `Could not find Payload import map folder. Looked in ${appLocation} and ${srcAppLocation}`,
       )
     }

packages/payload/src/index.ts

@@ -1000,9 +1000,13 @@ export const reload = async (
     })
   }
 
-  // Generate component map
+  // Generate import map
   if (skipImportMapGeneration !== true && config.admin?.importMap?.autoGenerate !== false) {
+    // This may run outside of the admin panel, e.g. in the user's frontend, where we don't have an import map file.
+    // We don't want to throw an error in this case, as it would break the user's frontend.
+    // => just skip it => ignoreResolveError: true
     await generateImportMap(config, {
+      ignoreResolveError: true,
       log: true,
     })
   }
@@ -1098,7 +1102,18 @@ export const getPayload = async (
       // will reach `if (cached.reload instanceof Promise) {` which then waits for the first reload to finish.
       cached.reload = new Promise((res) => (resolve = res))
       const config = await options.config
-      await reload(config, cached.payload, !options.importMap, options)
+
+      // Reload the payload instance after a config change (triggered by HMR in development).
+      // The second parameter (false) forces import map regeneration rather than deciding based on options.importMap.
+      //
+      // Why we always regenerate import map: getPayload() may be called from multiple sources (admin panel, frontend, etc.)
+      // that share the same cache but may pass different importMap values. Since call order is unpredictable,
+      // we cannot rely on options.importMap to determine if regeneration is needed.
+      //
+      // Example scenario: If the frontend calls getPayload() without importMap first, followed by the admin
+      // panel calling it with importMap, we'd incorrectly skip generation for the admin panel's needs.
+      // By always regenerating on reload, we ensure the import map stays in sync with the updated config.
+      await reload(config, cached.payload, false, options)
 
       resolve()
     }