payloadcms / payloadcms/payload
Document "type": "module" requirement for payload generate:types in Next.js
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 44.8k
- Forks
- 4.2k
- Avg merge
- 2d 21h
- Merged PRs (30d)
- 53
Description
Documentation Issue
Summary of the documentation issue
The docs do not explain that payload generate:types can fail in typical Next.js setups with ERR_MODULE_NOT_FOUND when payload.config.ts uses extensionless local imports (e.g. import { Users } from "./collections/Users"). There is no mention of the need for "type": "module" in package.json (or of the tsx workaround) to make type generation work. This leads to confusion and extra debugging when the command fails out of the box.
Additional Details
What happens: In a Next.js project without "type": "module", running payload generate:types (e.g. pnpm exec payload generate:types) fails with:
Error [ERR_MODULE_NOT_FOUND]: Cannot find module '.../collections/Users' imported from .../payload.config.ts
Why: Node ESM does not add file extensions. So extensionless imports in the config (e.g. ./collections/Users) are not resolved to Users.ts, and the CLI fails when loading the user config.
Working workarounds:
- Add
"type": "module"topackage.json— thenpayload generate:typesworks with the same extensionless imports. Tested with Next.js 16.1.6:next devandnext buildstill work. - Run via tsx:
tsx node_modules/payload/bin.js generate:types(withtsxas a devDependency), as noted in issue #14443.
Suggested doc changes: Under Generating TypeScript Interfaces (or a “Troubleshooting” section), add a short note that:
- In some setups (e.g. default Next.js), type generation may require
"type": "module"inpackage.json, and/or - If you see ERR_MODULE_NOT_FOUND on config imports, try adding
"type": "module"or using the tsx workaround above.
Related: Open PR #13282 proposes documenting the "type": "module" requirement but is stale; the same topic appears in issues #14443 and #14994.
Environment (for reference): Node v22.17.1, pnpm, Payload 3.79.0, Next.js 16.1.6.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.