doc: remove extensionless CJS exception for type:module by mcollina · Pull Request #62176 · nodejs/node

mcollina · 2026-03-10T07:10:06Z

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 · 2026-03-10T07:10:12Z

Review requested:

@nodejs/loaders

joyeecheung · 2026-03-10T14:16:57Z

doc/api/modules.md

-  [`"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


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

doc/api/modules.md

Co-authored-by: Geoffrey Booth <webadmin@geoffreybooth.com>

mcollina · 2026-03-22T15:28:35Z

@GeoffreyBooth I merged your edits.

GeoffreyBooth · 2026-03-22T16:25:44Z

@GeoffreyBooth I merged your edits.

I think something is buggy with the GitHub suggestions feature, because it looks like my suggestion got appended after the old text rather than replacing it:

doc/api/modules.md

nodejs-github-bot · 2026-03-26T02:30:25Z

CI: https://ci.nodejs.org/job/node-test-pull-request/71963/

Co-authored-by: Geoffrey Booth <webadmin@geoffreybooth.com>

mcollina · 2026-04-05T21:19:59Z

@GeoffreyBooth ptal

GeoffreyBooth

Okay so just to confirm, in 26.0.0+:

There are no more weird exceptions for extensionless files: they behave identically to .js files whether in a type: 'module' scope, a type: 'commonjs' scope, or a scope where there’s no type field.
Syntax detection only ever applies within a scope where there’s no type field.

Is this correct?

nodejs-github-bot · 2026-04-08T07:54:38Z

Commit Queue failed

- Loading data for nodejs/node/pull/62176
✔  Done loading data for nodejs/node/pull/62176
----------------------------------- PR info ------------------------------------
Title      doc: remove extensionless CJS exception for type:module (#62176)
Author     Matteo Collina <matteo.collina@gmail.com> (@mcollina)
Branch     mcollina:doc/remove-extensionless-cjs-exception -> nodejs:main
Labels     doc, module, semver-major
Commits    4
 - doc: remove extensionless CJS exception for type:module packages
 - Update modules.md
 - doc: fix duplicated wording in modules.md
 - Update doc/api/modules.md
Committers 2
 - Matteo Collina <hello@matteocollina.com>
 - GitHub <noreply@github.com>
PR-URL: https://github.com/nodejs/node/pull/62176
Refs: https://github.com/nodejs/node/pull/61600
Refs: https://github.com/nodejs/node/pull/62083
Refs: https://github.com/nodejs/node/issues/61971
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com>
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/62176
Refs: https://github.com/nodejs/node/pull/61600
Refs: https://github.com/nodejs/node/pull/62083
Refs: https://github.com/nodejs/node/issues/61971
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com>
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
--------------------------------------------------------------------------------
   ℹ  This PR was created on Tue, 10 Mar 2026 07:10:06 GMT
   ✔  Approvals: 3
   ✔  - Geoffrey Booth (@GeoffreyBooth): https://github.com/nodejs/node/pull/62176#pullrequestreview-4059937547
   ✔  - Ulises Gascón (@UlisesGascon): https://github.com/nodejs/node/pull/62176#pullrequestreview-3994329997
   ✔  - Paolo Insogna (@ShogunPanda) (TSC): https://github.com/nodejs/node/pull/62176#pullrequestreview-4060635747
   ✘  semver-major requires at least 2 TSC approvals
   ✔  Last GitHub CI successful
   ℹ  Green GitHub CI is sufficient
--------------------------------------------------------------------------------
   ✔  Aborted `git node land` session in /home/runner/work/node/node/.ncu

https://github.com/nodejs/node/actions/runs/24124327533

nodejs-github-bot · 2026-04-08T08:22:50Z

Commit Queue failed

- Loading data for nodejs/node/pull/62176 ✔ Done loading data for nodejs/node/pull/62176 ----------------------------------- PR info ------------------------------------ Title doc: remove extensionless CJS exception for type:module (#62176) Author Matteo Collina <matteo.collina@gmail.com> (@mcollina) Branch mcollina:doc/remove-extensionless-cjs-exception -> nodejs:main Labels doc, module, semver-major Commits 4 - doc: remove extensionless CJS exception for type:module packages - Update modules.md - doc: fix duplicated wording in modules.md - Update doc/api/modules.md Committers 2 - Matteo Collina <hello@matteocollina.com> - GitHub <noreply@github.com> PR-URL: https://github.com/nodejs/node/pull/62176 Refs: https://github.com/nodejs/node/pull/61600 Refs: https://github.com/nodejs/node/pull/62083 Refs: https://github.com/nodejs/node/issues/61971 Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com> Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Reviewed-By: Paolo Insogna <paolo@cowtech.it> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> ------------------------------ Generated metadata ------------------------------ PR-URL: https://github.com/nodejs/node/pull/62176 Refs: https://github.com/nodejs/node/pull/61600 Refs: https://github.com/nodejs/node/pull/62083 Refs: https://github.com/nodejs/node/issues/61971 Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com> Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Reviewed-By: Paolo Insogna <paolo@cowtech.it> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> -------------------------------------------------------------------------------- ℹ This PR was created on Tue, 10 Mar 2026 07:10:06 GMT ✔ Approvals: 4 ✔ - Geoffrey Booth (@GeoffreyBooth): https://github.com/nodejs/node/pull/62176#pullrequestreview-4059937547 ✔ - Ulises Gascón (@UlisesGascon): https://github.com/nodejs/node/pull/62176#pullrequestreview-3994329997 ✔ - Paolo Insogna (@ShogunPanda) (TSC): https://github.com/nodejs/node/pull/62176#pullrequestreview-4060635747 ✔ - Antoine du Hamel (@aduh95) (TSC): https://github.com/nodejs/node/pull/62176#pullrequestreview-4073605376 ✔ Last GitHub CI successful ℹ Green GitHub CI is sufficient -------------------------------------------------------------------------------- ✔ No git cherry-pick in progress ✔ No git am in progress ✔ No git rebase in progress -------------------------------------------------------------------------------- - Bringing origin/main up to date... From https://github.com/nodejs/node * branch main -> FETCH_HEAD ✔ origin/main is now up-to-date - Downloading patch for 62176 From https://github.com/nodejs/node * branch refs/pull/62176/merge -> FETCH_HEAD ✔ Fetched commits as 8a48913e1cd0..4b8b3c9ae834 -------------------------------------------------------------------------------- [main a6cb26bb09] doc: remove extensionless CJS exception for type:module packages Author: Matteo Collina <hello@matteocollina.com> Date: Tue Mar 10 08:09:38 2026 +0100 1 file changed, 2 insertions(+), 3 deletions(-) [main 930ee1a818] Update modules.md Author: Matteo Collina <matteo.collina@gmail.com> Date: Sun Mar 22 16:27:53 2026 +0100 1 file changed, 20 insertions(+), 1 deletion(-) [main a09ce3fa03] doc: fix duplicated wording in modules.md Author: Matteo Collina <hello@matteocollina.com> Date: Sun Mar 22 17:40:15 2026 +0100 1 file changed, 6 insertions(+), 27 deletions(-) [main 2deda1c3ae] Update doc/api/modules.md Author: Matteo Collina <matteo.collina@gmail.com> Date: Sun Apr 5 23:19:37 2026 +0200 1 file changed, 2 insertions(+) ✔ Patches applied There are 4 commits in the PR. Attempting autorebase. (node:378) [DEP0190] DeprecationWarning: Passing args to a child process with shell option true can lead to security vulnerabilities, as the arguments are not escaped, only concatenated. (Use `node --trace-deprecation ...` to show where the warning was created) Rebasing (2/8) Executing: git node land --amend --yes --------------------------------- New Message ---------------------------------- doc: remove extensionless CJS exception for type:module packages

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 #61600,
this change aligns the CJS documentation accordingly.

Refs: #61600
Refs: #62083
PR-URL: #62176
Refs: #61600
Refs: #62083
Refs: #61971
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com>
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

[detached HEAD f96466ee41] doc: remove extensionless CJS exception for type:module packages
Author: Matteo Collina <hello@matteocollina.com>
Date: Tue Mar 10 08:09:38 2026 +0100
1 file changed, 2 insertions(+), 3 deletions(-)
Rebasing (3/8)
Rebasing (4/8)
Executing: git node land --amend --yes
--------------------------------- New Message ----------------------------------
Update modules.md

Co-authored-by: Geoffrey Booth <webadmin@geoffreybooth.com>
PR-URL: #62176
Refs: #61600
Refs: #62083
Refs: #61971
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com>
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

[detached HEAD a146d7c646] Update modules.md
Author: Matteo Collina <matteo.collina@gmail.com>
Date: Sun Mar 22 16:27:53 2026 +0100
1 file changed, 20 insertions(+), 1 deletion(-)
Rebasing (5/8)
Rebasing (6/8)
Executing: git node land --amend --yes
--------------------------------- New Message ----------------------------------
doc: fix duplicated wording in modules.md

PR-URL: #62176
Refs: #61600
Refs: #62083
Refs: #61971
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com>
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

[detached HEAD 082dd1a258] doc: fix duplicated wording in modules.md
Author: Matteo Collina <hello@matteocollina.com>
Date: Sun Mar 22 17:40:15 2026 +0100
1 file changed, 6 insertions(+), 27 deletions(-)
Rebasing (7/8)
Rebasing (8/8)
Executing: git node land --amend --yes
--------------------------------- New Message ----------------------------------
Update doc/api/modules.md

Co-authored-by: Geoffrey Booth <webadmin@geoffreybooth.com>
PR-URL: #62176
Refs: #61600
Refs: #62083
Refs: #61971
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com>
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

[detached HEAD 6cb4dad26c] Update doc/api/modules.md
Author: Matteo Collina <matteo.collina@gmail.com>
Date: Sun Apr 5 23:19:37 2026 +0200
1 file changed, 2 insertions(+)
Successfully rebased and updated refs/heads/main.

ℹ Add commit-queue-squash label to land the PR as one commit, or commit-queue-rebase to land as separate commits.

https://github.com/nodejs/node/actions/runs/24125357599

nodejs-github-bot · 2026-04-08T08:50:23Z

Landed in ff08094

GeoffreyBooth · 2026-04-08T19:57:55Z

I don't think this was quite ready to land; my question above in #62176 (review) hasn't been answered. But if my assumptions there are correct then there's no need to revert. @aduh95 @mcollina

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

mcollina requested review from GeoffreyBooth and joyeecheung March 10, 2026 07:10

joyeecheung reviewed Mar 10, 2026

View reviewed changes

joyeecheung added the semver-major PRs that contain breaking changes and should be released in the next major version. label Mar 10, 2026

joyeecheung mentioned this pull request Mar 11, 2026

[25.x] module: fix extensionless CJS files in type:module packages #62083

Merged

GeoffreyBooth reviewed Mar 20, 2026

View reviewed changes

doc/api/modules.md Outdated Show resolved Hide resolved

Update modules.md

21ce4fb

Co-authored-by: Geoffrey Booth <webadmin@geoffreybooth.com>

mcollina added the request-ci Add this label to start a Jenkins CI on a PR. label Mar 22, 2026

doc: fix duplicated wording in modules.md

9342855

GeoffreyBooth approved these changes Mar 22, 2026

View reviewed changes

doc/api/modules.md Show resolved Hide resolved

GeoffreyBooth approved these changes Mar 22, 2026

View reviewed changes

GeoffreyBooth reviewed Mar 23, 2026

View reviewed changes

doc/api/modules.md Show resolved Hide resolved

UlisesGascon approved these changes Mar 23, 2026

View reviewed changes

github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Mar 26, 2026

Update doc/api/modules.md

4b8b3c9

Co-authored-by: Geoffrey Booth <webadmin@geoffreybooth.com>

GeoffreyBooth approved these changes Apr 5, 2026

View reviewed changes

ShogunPanda approved these changes Apr 6, 2026

View reviewed changes

mcollina added the commit-queue Add this label to land a pull request using GitHub Actions. label Apr 8, 2026

mcollina mentioned this pull request Apr 8, 2026

2026-04-21, Version 26.0.0 (Current) #62526

Open

nodejs-github-bot added commit-queue-failed An error occurred while landing this pull request using GitHub Actions. and removed commit-queue Add this label to land a pull request using GitHub Actions. labels Apr 8, 2026

aduh95 approved these changes Apr 8, 2026

View reviewed changes

aduh95 added commit-queue Add this label to land a pull request using GitHub Actions. and removed commit-queue-failed An error occurred while landing this pull request using GitHub Actions. labels Apr 8, 2026

nodejs-github-bot added commit-queue-failed An error occurred while landing this pull request using GitHub Actions. and removed commit-queue Add this label to land a pull request using GitHub Actions. labels Apr 8, 2026

nodejs-github-bot removed the commit-queue Add this label to land a pull request using GitHub Actions. label Apr 8, 2026

nodejs-github-bot merged commit ff08094 into nodejs:main Apr 8, 2026
39 checks passed

Uh oh!

Conversation

mcollina commented Mar 10, 2026

Uh oh!

nodejs-github-bot commented Mar 10, 2026

Uh oh!

joyeecheung Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mcollina commented Mar 22, 2026

Uh oh!

GeoffreyBooth commented Mar 22, 2026

Uh oh!

Uh oh!

Uh oh!

nodejs-github-bot commented Mar 26, 2026

Uh oh!

mcollina commented Apr 5, 2026

Uh oh!

GeoffreyBooth left a comment

Choose a reason for hiding this comment

Uh oh!

nodejs-github-bot commented Apr 8, 2026

Uh oh!

nodejs-github-bot commented Apr 8, 2026

PR-URL: #62176 Refs: #61600 Refs: #62083 Refs: #61971 Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com> Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Reviewed-By: Paolo Insogna <paolo@cowtech.it> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

[detached HEAD 6cb4dad26c] Update doc/api/modules.md Author: Matteo Collina <matteo.collina@gmail.com> Date: Sun Apr 5 23:19:37 2026 +0200 1 file changed, 2 insertions(+) Successfully rebased and updated refs/heads/main.

Uh oh!

Uh oh!

nodejs-github-bot commented Apr 8, 2026

Uh oh!

GeoffreyBooth commented Apr 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

PR-URL: #62176
Refs: #61600
Refs: #62083
Refs: #61971
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com>
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

[detached HEAD 6cb4dad26c] Update doc/api/modules.md
Author: Matteo Collina <matteo.collina@gmail.com>
Date: Sun Apr 5 23:19:37 2026 +0200
1 file changed, 2 insertions(+)
Successfully rebased and updated refs/heads/main.