Skip to content

doc: remove extensionless CJS exception for type:module#62176

Open
mcollina wants to merge 1 commit intonodejs:mainfrom
mcollina:doc/remove-extensionless-cjs-exception
Open

doc: remove extensionless CJS exception for type:module#62176
mcollina wants to merge 1 commit intonodejs:mainfrom
mcollina:doc/remove-extensionless-cjs-exception

Conversation

@mcollina
Copy link
Member

The CJS documentation has included an exception since v16 (added in #41383) stating that extensionless files in type: "module" packages are recognized as CommonJS when included via require(). This exception conflicts with the ESM resolution specification which states that extensionless files within a package scope with an explicit type field follow the format of the type field.

Since #61600, the behavior on main already matches the ESM spec: extensionless files respect the type field. This change aligns the CJS documentation accordingly by removing the contradicting exception.

For v25.x, #62083 restores the documented exception as a targeted fix to avoid breaking packages like yargs v17 that relied on the old behavior.

Refs: #61600
Refs: #62083
Refs: #61971

Remove the documented exception that extensionless files in
type: "module" packages are recognized as CommonJS when included
via require(). This exception conflicted with the ESM resolution
specification which states that extensionless files within a
package scope with an explicit type field follow the format of
the type field.

The behavior on main already matches the ESM spec since nodejs#61600,
this change aligns the CJS documentation accordingly.

Refs: nodejs#61600
Refs: nodejs#62083
@nodejs-github-bot
Copy link
Collaborator

Review requested:

  • @nodejs/loaders

@nodejs-github-bot nodejs-github-bot added doc Issues and PRs related to the documentations. module Issues and PRs related to the module subsystem. labels Mar 10, 2026
[`"type"`][] with a value of `"module"`, those files will be recognized as
CommonJS modules only if they are being included via `require()`, not when
used as the command-line entry point of the program).
[`"type"`][] with a value of `"module"`, those files will not be recognized as
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can just removed this entire point, because the opening paragraph says:

Node.js will treat the following as CommonJS modules

Instead, just add a new paragraph noting that files with extensions outside that set/files without extensions would be treated based on the type field in the package.json

@joyeecheung joyeecheung added the semver-major PRs that contain breaking changes and should be released in the next major version. label Mar 10, 2026
Comment on lines 77 to +96
By default, Node.js will treat the following as CommonJS modules:

* Files with a `.cjs` extension;

* Files with a `.js` extension when the nearest parent `package.json` file
contains a top-level field [`"type"`][] with a value of `"commonjs"`.

* Files with a `.js` extension or without an extension, when the nearest parent
`package.json` file doesn't contain a top-level field [`"type"`][] or there is
no `package.json` in any parent folder; unless the file contains syntax that
errors unless it is evaluated as an ES module. Package authors should include
the [`"type"`][] field, even in packages where all sources are CommonJS. Being
explicit about the `type` of the package will make things easier for build
tools and loaders to determine how the files in the package should be
interpreted.

* Files with an extension that is not `.mjs`, `.cjs`, `.json`, `.node`, or `.js`
(when the nearest parent `package.json` file contains a top-level field
[`"type"`][] with a value of `"module"`, those files will be recognized as
CommonJS modules only if they are being included via `require()`, not when
used as the command-line entry point of the program).
[`"type"`][] with a value of `"module"`, those files will not be recognized as
CommonJS modules).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
CommonJS modules).
By default, Node.js will treat the following as CommonJS modules:
* Files with a `.cjs` extension.
* Files with a `.js` extension or without an extension, when the nearest parent
`package.json` file contains a top-level field [`"type"`][] with a value of
`"commonjs"`.
* Files with a `.js` extension or without an extension, when the nearest parent
`package.json` file doesn't contain a top-level field [`"type"`][] or there is
no `package.json` in any parent folder; unless the file contains syntax that
errors unless it is evaluated as an ES module. Package authors should include
the [`"type"`][] field, even in packages where all sources are CommonJS. Being
explicit about the `type` of the package will make things easier for build
tools and loaders to determine how the files in the package should be
interpreted.
* Files with an extension that is not `.mjs`, `.cjs`, `.json`, `.node`, or `.js`,
when the nearest parent `package.json` file contains a top-level field
[`"type"`][] with a value of `"module"`.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

doc Issues and PRs related to the documentations. module Issues and PRs related to the module subsystem. semver-major PRs that contain breaking changes and should be released in the next major version.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants