From 79a6c9a56b22e39043a07217e6699f83af63b94c Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Tue, 28 Dec 2021 12:16:03 +0100 Subject: [PATCH 1/8] doc: clarify `require` behavior with non `.js` extensions Refs: https://github.com/nodejs/node/discussions/41333 --- doc/api/modules.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/api/modules.md b/doc/api/modules.md index bd975d273e2366..225eba5f960e54 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -377,9 +377,9 @@ If the exact filename is not found, then Node.js will attempt to load the required filename with the added extensions: `.js`, `.json`, and finally `.node`. -`.js` files are interpreted as JavaScript text files, and `.json` files are -parsed as JSON text files. `.node` files are interpreted as compiled addon -modules loaded with `process.dlopen()`. +`.json` files are parsed as JSON text files, `.node` files are interpreted as +compiled addon modules loaded with `process.dlopen()`. Files using an unknown +extension (or no extension at all) are parsed as JavaScript text files. A required module prefixed with `'/'` is an absolute path to the file. For example, `require('/home/marco/foo.js')` will load the file at From 9d02904215b334c2138301ecc3eff1f8723fd080 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Tue, 28 Dec 2021 16:54:45 +0100 Subject: [PATCH 2/8] Update doc/api/modules.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Michaël Zasso --- doc/api/modules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/modules.md b/doc/api/modules.md index 225eba5f960e54..8b144ba718f5d3 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -378,7 +378,7 @@ required filename with the added extensions: `.js`, `.json`, and finally `.node`. `.json` files are parsed as JSON text files, `.node` files are interpreted as -compiled addon modules loaded with `process.dlopen()`. Files using an unknown +compiled addon modules loaded with `process.dlopen()`. Files using any other extension (or no extension at all) are parsed as JavaScript text files. A required module prefixed with `'/'` is an absolute path to the file. For From 761197cc62413888b1182b214ff10ab46e2dcebe Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Wed, 29 Dec 2021 21:50:14 +0100 Subject: [PATCH 3/8] parse goal --- doc/api/modules.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/api/modules.md b/doc/api/modules.md index 8b144ba718f5d3..1da05db5276eb4 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -379,7 +379,9 @@ required filename with the added extensions: `.js`, `.json`, and finally `.json` files are parsed as JSON text files, `.node` files are interpreted as compiled addon modules loaded with `process.dlopen()`. Files using any other -extension (or no extension at all) are parsed as JavaScript text files. +extension (or no extension at all) are parsed as JavaScript text files. Refer to +the [Determining module system][] section to understand what parse goal will be +used. A required module prefixed with `'/'` is an absolute path to the file. For example, `require('/home/marco/foo.js')` will load the file at @@ -1036,6 +1038,7 @@ This section was moved to * `sourceMap.payload` * `sourceMap.findEntry(lineNumber, columnNumber)` +[Determining module system]: packages.md#determining-module-system [ECMAScript Modules]: esm.md [GLOBAL_FOLDERS]: #loading-from-the-global-folders [`"main"`]: packages.md#main From 046e1026dea8d2d6e1bb0529d6730a02bd09997d Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Thu, 30 Dec 2021 15:57:18 +0100 Subject: [PATCH 4/8] `.cjs` and `.mjs` in CJS --- doc/api/modules.md | 26 +++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/doc/api/modules.md b/doc/api/modules.md index 1da05db5276eb4..d82849b0cdd5db 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -63,6 +63,17 @@ module.exports = class Square { The module system is implemented in the `require('module')` module. +## Enabling + + + +Node.js treats JavaScript code as CommonJS modules by default. +Authors can tell Node.js to treat JavaScript code as CommonJS modules +via the `.cjs` file extension, the `package.json` [`"type"`][] field, or the +`--input-type` flag. See +[Determining module system](packages.md#determining-module-system) for more +details. + ## Accessing the main module @@ -133,10 +144,13 @@ relative, and based on the real path of the files making the calls to ## The `.mjs` extension -It is not possible to `require()` files that have the `.mjs` extension. -Attempting to do so will throw [an error][]. The `.mjs` extension is -reserved for [ECMAScript Modules][] which cannot be loaded via `require()`. -See [ECMAScript Modules][] for more details. +Due to the synchronous nature of `require()`, it is not possible to use it to +load ECMAScript module files. Attempting to do so will throw a +[`ERR_REQUIRE_ESM`][] error. Use [`import()`][] instead. + +The `.mjs` extension is reserved for [ECMAScript Modules][] which cannot be +loaded via `require()`. See [Determining module system][] section for more info +regarding which files are parsed as ECMAScript modules. ## All together... @@ -1042,16 +1056,18 @@ This section was moved to [ECMAScript Modules]: esm.md [GLOBAL_FOLDERS]: #loading-from-the-global-folders [`"main"`]: packages.md#main +[`"type"`]: packages.md#type +[`ERR_REQUIRE_ESM`]: errors.md#err_require_esm [`Error`]: errors.md#class-error [`__dirname`]: #__dirname [`__filename`]: #__filename +[`import()`]: https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#Dynamic_Imports [`module.children`]: #modulechildren [`module.id`]: #moduleid [`module` object]: #the-module-object [`package.json`]: packages.md#nodejs-packagejson-field-definitions [`path.dirname()`]: path.md#pathdirnamepath [`require.main`]: #requiremain -[an error]: errors.md#err_require_esm [exports shortcut]: #exports-shortcut [module resolution]: #all-together [native addons]: addons.md From 5ed7e1cdf3d36a4e396e6cceade02743f872b4ea Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Sat, 1 Jan 2022 16:50:25 +0100 Subject: [PATCH 5/8] `.cjs` files always need their extension to be included --- doc/api/modules.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/api/modules.md b/doc/api/modules.md index d82849b0cdd5db..ab16f2f404b8d1 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -389,7 +389,9 @@ correctly within an application. If the exact filename is not found, then Node.js will attempt to load the required filename with the added extensions: `.js`, `.json`, and finally -`.node`. +`.node`. When loading a file that has a different extension (e.g. `.cjs`), its +full name must be included, including its file extension (e.g. +`require('./file.cjs')`). `.json` files are parsed as JSON text files, `.node` files are interpreted as compiled addon modules loaded with `process.dlopen()`. Files using any other From 40b46cb6299ae853881ea74ae13f704f4da600d8 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Sat, 1 Jan 2022 20:09:49 +0100 Subject: [PATCH 6/8] clean up links --- doc/api/modules.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/api/modules.md b/doc/api/modules.md index ab16f2f404b8d1..871ffadf8ef979 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -70,9 +70,7 @@ The module system is implemented in the `require('module')` module. Node.js treats JavaScript code as CommonJS modules by default. Authors can tell Node.js to treat JavaScript code as CommonJS modules via the `.cjs` file extension, the `package.json` [`"type"`][] field, or the -`--input-type` flag. See -[Determining module system](packages.md#determining-module-system) for more -details. +[`--input-type`][] flag. See [Determining module system][] for more details. ## Accessing the main module @@ -1059,6 +1057,7 @@ This section was moved to [GLOBAL_FOLDERS]: #loading-from-the-global-folders [`"main"`]: packages.md#main [`"type"`]: packages.md#type +[`--input-type`]: cli.md#--input-typetype [`ERR_REQUIRE_ESM`]: errors.md#err_require_esm [`Error`]: errors.md#class-error [`__dirname`]: #__dirname From 7639c2fe2877f7681322f28557672fbe5e5bc0c8 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Sun, 2 Jan 2022 15:59:17 +0100 Subject: [PATCH 7/8] Remove enbling section as it doesn't have consensus --- doc/api/modules.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/doc/api/modules.md b/doc/api/modules.md index 871ffadf8ef979..a031200b1cda08 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -63,15 +63,6 @@ module.exports = class Square { The module system is implemented in the `require('module')` module. -## Enabling - - - -Node.js treats JavaScript code as CommonJS modules by default. -Authors can tell Node.js to treat JavaScript code as CommonJS modules -via the `.cjs` file extension, the `package.json` [`"type"`][] field, or the -[`--input-type`][] flag. See [Determining module system][] for more details. - ## Accessing the main module @@ -1056,8 +1047,6 @@ This section was moved to [ECMAScript Modules]: esm.md [GLOBAL_FOLDERS]: #loading-from-the-global-folders [`"main"`]: packages.md#main -[`"type"`]: packages.md#type -[`--input-type`]: cli.md#--input-typetype [`ERR_REQUIRE_ESM`]: errors.md#err_require_esm [`Error`]: errors.md#class-error [`__dirname`]: #__dirname From 9407cd5563769a059d627cb8b6620e7b984c536b Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Sun, 2 Jan 2022 16:10:58 +0100 Subject: [PATCH 8/8] remove repetition --- doc/api/modules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/modules.md b/doc/api/modules.md index a031200b1cda08..264303006ae224 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -379,7 +379,7 @@ correctly within an application. If the exact filename is not found, then Node.js will attempt to load the required filename with the added extensions: `.js`, `.json`, and finally `.node`. When loading a file that has a different extension (e.g. `.cjs`), its -full name must be included, including its file extension (e.g. +full name must be passed to `require()`, including its file extension (e.g. `require('./file.cjs')`). `.json` files are parsed as JSON text files, `.node` files are interpreted as