payloadcms / payloadcms/payload

Document "type": "module" requirement for payload generate:types in Next.js

Open
#15,875 1 comment 1 reaction 1 assignee View on GitHub

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:

  1. Add "type": "module" to package.json — then payload generate:types works with the same extensionless imports. Tested with Next.js 16.1.6: next dev and next build still work.
  2. Run via tsx: tsx node_modules/payload/bin.js generate:types (with tsx as 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" in package.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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.