Hydration errors that show up as import map/lexical issues during dev fixed with importMap.js and importMap.ts rebuild

[cinchpin]

In case it helps anyone else, I have one more thing to check when you encounter hydration errors showing up as Next.js import-map / lexical errors in dev mode when using Payload 3.x on Next.js 15+.

I went through all github issues, followed accepted fixes, including the barrel file issue. I changed types and import map load order in my startup script per Mikrut's advice. Reverted node.js to 20.x. Nothing worked. I tried to find a relevant open issue to attach this fix to, but didn't see one, but since I wasted so much time on it I thought I'd post in case it's of any use.

In my case, the issue was a mismatch between importMap.js and importMap.ts. Since my dev startup script rebuilds types and import map each time (and bc I'm a bit of a numpty) I'd not gone in to eyeball the files directly. Somehow, my importMap.ts contained "export const importMap = {}" which Payload startup didn't clock as empty contents and read as good to go . Repopulating the file manually (or i suppose zeroing or removing it) meant the back end and front end were working from the same recipe again and my hydration errors disappeared.

[alstjd0051]

Summary of the cause: During development, importMap.js and importMap.ts contained different mappings, so the server and client used different module maps, which resulted in a hydration mismatch.

Things to check: If your build script auto-generates importMap.ts, verify that the file actually contains the import map. If it exports an empty object ({}) then it's effectively blank and will cause issues.

Solution: Regenerate both files with the correct import mappings or delete/reset any empty file and rebuild so that both server and client use the same import map.

Verification: After making the change, restart your dev server and confirm that the previous import map/lexical errors and hydration mismatch no longer occur.