From 1b1159ae502a134c48427f6351627d32767539af Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Sun, 2 Jan 2022 19:06:35 +0100 Subject: [PATCH 01/14] doc: clarify module system selection Refs: https://github.com/nodejs/node/pull/41345#discussion_r777115823 --- doc/api/esm.md | 12 +++++++----- doc/api/modules.md | 16 +++++++++++++++- doc/api/packages.md | 34 ++++++++++++++++++++++++++-------- 3 files changed, 48 insertions(+), 14 deletions(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index 445b608d9219d8..36fd491c0761c1 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -94,12 +94,12 @@ provides interoperability between them and its original module format, -Node.js treats JavaScript code as CommonJS modules by default. -Authors can tell Node.js to treat JavaScript code as ECMAScript modules +Node.js has two module systems: [CommonJS][] modules and ECMAScript modules. + +Authors can tell Node.js to use the ECMAScript modules loader via the `.mjs` file extension, the `package.json` [`"type"`][] field, or the -`--input-type` flag. See -[Modules: Packages](packages.md#determining-module-system) for more -details. +[`--input-type`][] flag. Outside of those cases, Node.js will use the CommonJS +module loader. See [Determining module system][] for more details. @@ -1425,6 +1425,7 @@ success! [CommonJS]: modules.md [Conditional exports]: packages.md#conditional-exports [Core modules]: modules.md#core-modules +[Determining module system]: packages.md#determining-module-system [Dynamic `import()`]: https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#Dynamic_Imports [ECMAScript Top-Level `await` proposal]: https://github.com/tc39/proposal-top-level-await/ [ES Module Integration Proposal for WebAssembly]: https://github.com/webassembly/esm-integration @@ -1437,6 +1438,7 @@ success! [WHATWG JSON modules specification]: https://html.spec.whatwg.org/#creating-a-json-module-script [`"exports"`]: packages.md#exports [`"type"`]: packages.md#type +[`--input-type`]: cli.md#--input-typetype [`ArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer [`SharedArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer [`TypedArray`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray diff --git a/doc/api/modules.md b/doc/api/modules.md index 264303006ae224..fca365df4ed815 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -61,7 +61,18 @@ module.exports = class Square { }; ``` -The module system is implemented in the `require('module')` module. +The CommonJS module system is implemented in the [`module` core module][]. + +## Enabling + + + +Node.js has two module systems: CommonJS modules and [ECMAScript modules][]. + +Authors can tell Node.js to use the ECMAScript modules loader +via the `.mjs` file extension, the `package.json` [`"type"`][] field, or the +[`--input-type`][] flag. Outside of those cases, Node.js will use the CommonJS +module loader. See [Determining module system][] for more details. ## Accessing the main module @@ -1047,6 +1058,8 @@ 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 @@ -1054,6 +1067,7 @@ This section was moved to [`import()`]: https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#Dynamic_Imports [`module.children`]: #modulechildren [`module.id`]: #moduleid +[`module` core module]: module.md [`module` object]: #the-module-object [`package.json`]: packages.md#nodejs-packagejson-field-definitions [`path.dirname()`]: path.md#pathdirnamepath diff --git a/doc/api/packages.md b/doc/api/packages.md index 9529685b953127..76055fe1649f0c 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -51,12 +51,13 @@ along with a reference for the [`package.json`][] fields defined by Node.js. ## Determining module system Node.js will treat the following as [ES modules][] when passed to `node` as the -initial input, or when referenced by `import` statements within ES module code: +initial input, or when referenced by `import` statements or `import()` +expressions: -* Files ending in `.mjs`. +* Files whose name ends in `.mjs`. -* Files ending in `.js` when the nearest parent `package.json` file contains a - top-level [`"type"`][] field with a value of `"module"`. +* Files whose name ends in `.js` when the nearest parent `package.json` file + contains a top-level [`"type"`][] field with a value of `"module"`. * Strings passed in as an argument to `--eval`, or piped to `node` via `STDIN`, with the flag `--input-type=module`. @@ -67,12 +68,12 @@ field, or string input without the flag `--input-type`. This behavior is to preserve backward compatibility. However, now that Node.js supports both CommonJS and ES modules, it is best to be explicit whenever possible. Node.js will treat the following as CommonJS when passed to `node` as the initial input, -or when referenced by `import` statements within ES module code: +or when referenced by `import` statements or `import()` expressions: -* Files ending in `.cjs`. +* Files whose name ends in `.cjs`. -* Files ending in `.js` when the nearest parent `package.json` file contains a - top-level field [`"type"`][] with a value of `"commonjs"`. +* Files whose name ends in `.js` when the nearest parent `package.json` file + contains a top-level field [`"type"`][] with a value of `"commonjs"`. * Strings passed in as an argument to `--eval` or `--print`, or piped to `node` via `STDIN`, with the flag `--input-type=commonjs`. @@ -83,6 +84,23 @@ future-proof the package in case the default type of Node.js ever changes, and it will also make things easier for build tools and loaders to determine how the files in the package should be interpreted. +Node.js will refuse to load the following when passed to `node` as the +initial input and the nearest parent `package.json` file contains a top-level +[`"type"`][] field with a value of `"module"`: + +* Files whose name doesn't end in `.js`, `.mjs`, `.cjs`, or `.wasm`. + +Passing to `node` as the initial input when the nearest parent `package.json` +file contains a top-level [`"type"`][] field with a value of `"commonjs"`, or +when referenced by `require()` calls: + +* Files whose name ends in `.node` are interpreted as + compiled addon modules loaded with `process.dlopen()`. + +* Files whose name ends in `.json` are parsed as JSON text files. + +* Any other files will be treated as a [CommonJS][] module. + ### `package.json` and file extensions Within a package, the [`package.json`][] [`"type"`][] field defines how From dd7140fa8916845a4db00c3c8aaf0aba17c338b7 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Wed, 5 Jan 2022 22:46:30 +0100 Subject: [PATCH 02/14] Address review comments --- doc/api/cli.md | 34 +++++++++++++++++++++++++++++++--- doc/api/modules.md | 25 ++++++++++++++++++++----- doc/api/packages.md | 28 ++++++---------------------- doc/api/synopsis.md | 2 +- tools/doc/links-mapper.json | 2 +- 5 files changed, 59 insertions(+), 32 deletions(-) diff --git a/doc/api/cli.md b/doc/api/cli.md index 1c04da298b3760..9d7d2cab244762 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -1,4 +1,4 @@ -# Command-line options +# Command-line API @@ -11,9 +11,9 @@ To view this documentation as a manual page in a terminal, run `man node`. ## Synopsis -`node [options] [V8 options] [script.js | -e "script" | -] [--] [arguments]` +`node [options] [V8 options] [ | -e "script" | -] [--] [arguments]` -`node inspect [script.js | -e "script" | :] …` +`node inspect [ | -e "script" | :] …` `node --v8-options` @@ -21,6 +21,30 @@ Execute without arguments to start the [REPL][]. For more info about `node inspect`, see the [debugger][] documentation. +## Program entry point + +The program entry point is a specifier-like string. That string is first passed +through `path.resolve()` and the [CommonJS][] modules loader. If no +corresponding module, an error is thrown. + +If a module is found, its path will be passed to ECMAScript Module loader if: + +* The file has a `.mjs` extension, +* Or the file nearest parent `package.json` file + contains a top-level [`"type"`][] field with a value of `"module"`, +* Or if the program was started with a command-line flag that forces the entry + point to be loaded with ECMAScript Module loader. + +Otherwise the file is loaded using the CommonJS modules loader. See +[File modules][] section for more details. + +### ECMAScript modules loader entry point caveat + +When loading the program entry point using [ECMAScript Module loader][], the `node` +command will accept as input only files with `.js`, `.mjs`, or `.cjs` +extensions; and with `.wasm` extensions when +[`--experimental-wasm-modules`][] is enabled. + ## Options -Specify the `module` of a custom experimental [ECMAScript Module loader][]. -`module` may be either a path to a file, or an ECMAScript Module name. +Specify the `module` of a custom experimental [ECMAScript module loader][]. +`module` may be any string accepted as an [`import` specifier][]. ### `--experimental-policy` @@ -1953,7 +1955,7 @@ $ node --max-old-space-size=1536 index.js [Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/ [CommonJS]: modules.md -[ECMAScript Module loader]: esm.md#loaders +[ECMAScript module loader]: esm.md#loaders [File modules]: modules.md#file-modules [OSSL_PROVIDER-legacy]: https://www.openssl.org/docs/man3.0/man7/OSSL_PROVIDER-legacy.html [REPL]: repl.md @@ -1977,6 +1979,7 @@ $ node --max-old-space-size=1536 index.js [`dns.lookup()`]: dns.md#dnslookuphostname-options-callback [`dns.setDefaultResultOrder()`]: dns.md#dnssetdefaultresultorderorder [`dnsPromises.lookup()`]: dns.md#dnspromiseslookuphostname-options +[`import` specifier]: esm.md#import-specifiers [`process.setUncaughtExceptionCaptureCallback()`]: process.md#processsetuncaughtexceptioncapturecallbackfn [`tls.DEFAULT_MAX_VERSION`]: tls.md#tlsdefault_max_version [`tls.DEFAULT_MIN_VERSION`]: tls.md#tlsdefault_min_version diff --git a/doc/api/modules.md b/doc/api/modules.md index 81ab4d3d7d3b3d..e2667118f83aab 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -87,8 +87,8 @@ By default, Node.js will treat the following as CommonJS modules: See [Determining module system][] for more details. -Calling `require()` always use the CommonJS loader, calling `import()` always -use the [ECMAScript modules][] loader. +Calling `require()` always use the CommonJS module loader, calling `import()` +always use the ECMAScript module loader. ## Accessing the main module diff --git a/doc/api/packages.md b/doc/api/packages.md index c56aa412d95183..5785ee42ee3757 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -54,7 +54,7 @@ Node.js will treat the following as [ES modules][] when passed to `node` as the initial input, or when referenced by `import` statements or `import()` expressions: -* Files with a `.mjs` extension. +* Files with an `.mjs` extension. * Files with a `.js` extension when the nearest parent `package.json` file contains a top-level [`"type"`][] field with a value of `"module"`. From c19d1612d1bd0d57448411622e3a4eeda5550803 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Fri, 7 Jan 2022 19:52:27 +0100 Subject: [PATCH 04/14] fixup! --- doc/api/cli.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/api/cli.md b/doc/api/cli.md index 7b14ff45a246d3..84a424c98b1241 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -28,7 +28,7 @@ absolute path, it's resolved as a relative path from the current working directory. That path is then resolved by [CommonJS][] module loader. If no corresponding file is found, an error is thrown. -If a file is found, its path will be passed to [ECMAScript module loader][] +If a file is found, its path will be passed to the [ECMAScript module loader][] under any of the following conditions: * The file has an `.mjs` extension. @@ -37,13 +37,13 @@ under any of the following conditions: * If the program was started with a command-line flag that forces the entry point to be loaded with ECMAScript module loader. -Otherwise the file is loaded using the CommonJS module loader. See +Otherwise, the file is loaded using the CommonJS module loader. See [File modules][] for more details. ### ECMAScript modules loader entry point caveat -When loading the program entry point using [ECMAScript module loader][], the `node` -command will accept as input only files with `.js`, `.mjs`, or `.cjs` +When loading [ECMAScript module loader][] loads the program entry point, the `node` +command will only accept as input only files with `.js`, `.mjs`, or `.cjs` extensions; and with `.wasm` extensions when [`--experimental-wasm-modules`][] is enabled. From ce3edd033a046c0ea028d404305bbfb214c1c714 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Sat, 8 Jan 2022 17:21:26 +0100 Subject: [PATCH 05/14] fixup! --- doc/api/cli.md | 4 ++-- doc/api/packages.md | 38 +++++++++++++++++++++++++++++++++++++ tools/doc/links-mapper.json | 2 +- 3 files changed, 41 insertions(+), 3 deletions(-) diff --git a/doc/api/cli.md b/doc/api/cli.md index 84a424c98b1241..9aa94b26d2fea1 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -38,7 +38,7 @@ under any of the following conditions: point to be loaded with ECMAScript module loader. Otherwise, the file is loaded using the CommonJS module loader. See -[File modules][] for more details. +[Modules loaders][] for more details. ### ECMAScript modules loader entry point caveat @@ -1956,7 +1956,7 @@ $ node --max-old-space-size=1536 index.js [Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/ [CommonJS]: modules.md [ECMAScript module loader]: esm.md#loaders -[File modules]: modules.md#file-modules +[Modules loaders]: packages.md#modules-loaders [OSSL_PROVIDER-legacy]: https://www.openssl.org/docs/man3.0/man7/OSSL_PROVIDER-legacy.html [REPL]: repl.md [ScriptCoverage]: https://chromedevtools.github.io/devtools-protocol/tot/Profiler#type-ScriptCoverage diff --git a/doc/api/packages.md b/doc/api/packages.md index 5785ee42ee3757..84bffe80d788df 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -85,6 +85,41 @@ future-proof the package in case the default type of Node.js ever changes, and it will also make things easier for build tools and loaders to determine how the files in the package should be interpreted. +### Modules loaders + +Node.js has two system for resolving a specifier and load modules. + +There is the CommonJS module loader: + +* It is fully synchronous. +* It is monkey patchable. +* When resolving a specifier, if no exact match is found, it will try to add + extensions (`.js`, `.json`, and finally `.node`). +* It supports [folders as modules][]. +* It treats `.json` as JSON text files. +* `.node` files are interpreted as compiled addon modules loaded with + `process.dlopen()`. +* It treats files that do not have `.json` or `.node` extension as JavaScript + text files. +* It cannot be used to load ECMAScript modules. Attempting to do so will result + in a [`ERR_REQUIRE_ESM`][] error. +* It can be accessed using `require` function. + +There is the ECMAScript module loader: + +* It is Asynchronous. +* It is not monkey patchable, can be customized using [loader hooks][]. +* No extension searching, the specifier must point to the exact URL of the file. +* It does not support folders as modules. +* Import assertion are needed to load JSON modules (behind + `--experimental-json-modules` flag). +* It only accepts `.js`, `.mjs`, and `.cjs` extensions for JavaScript text + files. +* It can be used to load (JavaScript) CommonJS modules. It passes the module + content through the `es-module-lexer` to assess what are its exports, convert + its URL to an absolute path and load it using the CommonJS module loader. +* It can be accessed using `import`. + ### `package.json` and file extensions Within a package, the [`package.json`][] [`"type"`][] field defines how @@ -1235,9 +1270,12 @@ This field defines [subpath imports][] for the current package. [`--conditions` / `-C` flag]: #resolving-user-conditions [`--no-addons` flag]: cli.md#--no-addons [`ERR_PACKAGE_PATH_NOT_EXPORTED`]: errors.md#err_package_path_not_exported +[`ERR_REQUIRE_ESM`]: errors.md#err_require_esm [`esm`]: https://github.com/standard-things/esm#readme [`package.json`]: #nodejs-packagejson-field-definitions [entry points]: #package-entry-points +[folders as modules]: modules.md#folders-as-modules +[loader hooks]: esm.md#loaders [self-reference]: #self-referencing-a-package-using-its-name [subpath exports]: #subpath-exports [subpath imports]: #subpath-imports diff --git a/tools/doc/links-mapper.json b/tools/doc/links-mapper.json index 76d287eb275034..211ba70c0b5991 100644 --- a/tools/doc/links-mapper.json +++ b/tools/doc/links-mapper.json @@ -3,4 +3,4 @@ "command line options": "cli.html#options", "web server": "http.html" } -} \ No newline at end of file +} From be6f7916ff730b028f2a29497651bfab6d7f521d Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Mon, 10 Jan 2022 01:21:36 +0100 Subject: [PATCH 06/14] fixup! --- 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 e2667118f83aab..b86f3dfde2519a 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -77,7 +77,9 @@ By default, Node.js will treat the following as CommonJS modules: contains a top-level field [`"type"`][] with a value of `"commonjs"`. * Files with a `.js` extension when the nearest parent `package.json` file - doesn't contain a top-level field [`"type"`][]. + doesn't contain a top-level field [`"type"`][]. Package authors should + include the [`"type"`][] field, even in packages where all sources are + CommonJS, in case the default ever changes. * 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 From e9c0b15a73f1a508bae95f85008ef395c87953c9 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Tue, 11 Jan 2022 19:13:47 +0100 Subject: [PATCH 07/14] fixup! --- doc/api/modules.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/api/modules.md b/doc/api/modules.md index b86f3dfde2519a..b1fad001adb6d1 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -77,9 +77,11 @@ By default, Node.js will treat the following as CommonJS modules: contains a top-level field [`"type"`][] with a value of `"commonjs"`. * Files with a `.js` extension when the nearest parent `package.json` file - doesn't contain a top-level field [`"type"`][]. Package authors should - include the [`"type"`][] field, even in packages where all sources are - CommonJS, in case the default ever changes. + doesn't contain a top-level field [`"type"`][]. 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 From 4c697b748e3e4f81e61793cf9a7181abd526447a Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Thu, 13 Jan 2022 12:39:13 +0100 Subject: [PATCH 08/14] Apply suggestions from code review Co-authored-by: Geoffrey Booth <456802+GeoffreyBooth@users.noreply.github.com> --- doc/api/modules.md | 2 +- doc/api/packages.md | 18 ++++++++++-------- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/doc/api/modules.md b/doc/api/modules.md index b1fad001adb6d1..72db80e95808b1 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -91,7 +91,7 @@ By default, Node.js will treat the following as CommonJS modules: See [Determining module system][] for more details. -Calling `require()` always use the CommonJS module loader, calling `import()` +Calling `require()` always use the CommonJS module loader. Calling `import()` always use the ECMAScript module loader. ## Accessing the main module diff --git a/doc/api/packages.md b/doc/api/packages.md index 84bffe80d788df..d026667504d506 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -87,7 +87,7 @@ files in the package should be interpreted. ### Modules loaders -Node.js has two system for resolving a specifier and load modules. +Node.js has two systems for resolving a specifier and loading modules. There is the CommonJS module loader: @@ -99,7 +99,7 @@ There is the CommonJS module loader: * It treats `.json` as JSON text files. * `.node` files are interpreted as compiled addon modules loaded with `process.dlopen()`. -* It treats files that do not have `.json` or `.node` extension as JavaScript +* It treats all files that lack `.json` or `.node` extensions as JavaScript text files. * It cannot be used to load ECMAScript modules. Attempting to do so will result in a [`ERR_REQUIRE_ESM`][] error. @@ -111,14 +111,16 @@ There is the ECMAScript module loader: * It is not monkey patchable, can be customized using [loader hooks][]. * No extension searching, the specifier must point to the exact URL of the file. * It does not support folders as modules. -* Import assertion are needed to load JSON modules (behind +* It can load JSON modules, but an import assertion is required (behind `--experimental-json-modules` flag). -* It only accepts `.js`, `.mjs`, and `.cjs` extensions for JavaScript text +* It accepts only `.js`, `.mjs`, and `.cjs` extensions for JavaScript text files. -* It can be used to load (JavaScript) CommonJS modules. It passes the module - content through the `es-module-lexer` to assess what are its exports, convert - its URL to an absolute path and load it using the CommonJS module loader. -* It can be accessed using `import`. +* It can be used to load JavaScript CommonJS modules. Such modules + are passed through the `es-module-lexer` to try to identify named exports, + which are available if they can be determined through static analysis. + Imported CommonJS modules have their URLs converted to absolute + paths and are then loaded via the CommonJS module loader. +* It is responsible for handling `import` statements and `import()` expressions. ### `package.json` and file extensions From 2cea6a8fcd4ba7ccb9a7dfe632ba33b489786f42 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Thu, 13 Jan 2022 12:52:24 +0100 Subject: [PATCH 09/14] fixup! --- doc/api/packages.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index d026667504d506..ca882c77627372 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -92,6 +92,7 @@ Node.js has two systems for resolving a specifier and loading modules. There is the CommonJS module loader: * It is fully synchronous. +* It is responsible for handling `require()` calls. * It is monkey patchable. * When resolving a specifier, if no exact match is found, it will try to add extensions (`.js`, `.json`, and finally `.node`). @@ -103,14 +104,16 @@ There is the CommonJS module loader: text files. * It cannot be used to load ECMAScript modules. Attempting to do so will result in a [`ERR_REQUIRE_ESM`][] error. -* It can be accessed using `require` function. There is the ECMAScript module loader: -* It is Asynchronous. +* It is asynchronous. +* It is responsible for handling `import` statements and `import()` expressions. * It is not monkey patchable, can be customized using [loader hooks][]. -* No extension searching, the specifier must point to the exact URL of the file. -* It does not support folders as modules. +* No extension searching, a file extension must be provided when the specifier + is a relative or absolute file URL. +* It does not support folders as modules, directory indexes (e.g. + `'./startup/index.js'`) must be fully specified. * It can load JSON modules, but an import assertion is required (behind `--experimental-json-modules` flag). * It accepts only `.js`, `.mjs`, and `.cjs` extensions for JavaScript text @@ -120,7 +123,6 @@ There is the ECMAScript module loader: which are available if they can be determined through static analysis. Imported CommonJS modules have their URLs converted to absolute paths and are then loaded via the CommonJS module loader. -* It is responsible for handling `import` statements and `import()` expressions. ### `package.json` and file extensions From 21b45bf922d2768ce10d480a9c843ec20b92d9f3 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Fri, 14 Jan 2022 00:45:46 +0100 Subject: [PATCH 10/14] fixup! --- doc/api/packages.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index ca882c77627372..4aa743d948d336 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -103,7 +103,8 @@ There is the CommonJS module loader: * It treats all files that lack `.json` or `.node` extensions as JavaScript text files. * It cannot be used to load ECMAScript modules. Attempting to do so will result - in a [`ERR_REQUIRE_ESM`][] error. + in a [`ERR_REQUIRE_ESM`][] error. When used to load a JavaScript text file + that is not an ECMAScript module, it loads it as a CommonJS module. There is the ECMAScript module loader: From 93d6a233cf3afb504b62c6de9396e9edccd1da57 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Fri, 14 Jan 2022 11:33:03 +0100 Subject: [PATCH 11/14] fixup! --- doc/api/packages.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index 4aa743d948d336..48acc6905c8b14 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -102,17 +102,18 @@ There is the CommonJS module loader: `process.dlopen()`. * It treats all files that lack `.json` or `.node` extensions as JavaScript text files. -* It cannot be used to load ECMAScript modules. Attempting to do so will result - in a [`ERR_REQUIRE_ESM`][] error. When used to load a JavaScript text file - that is not an ECMAScript module, it loads it as a CommonJS module. +* It cannot be used to load ECMAScript modules (although it is possible to + [load ECMASCript modules from CommonJS modules][]). When used to load a + JavaScript text file that is not an ECMAScript module, it loads it as a + CommonJS module. There is the ECMAScript module loader: * It is asynchronous. * It is responsible for handling `import` statements and `import()` expressions. * It is not monkey patchable, can be customized using [loader hooks][]. -* No extension searching, a file extension must be provided when the specifier - is a relative or absolute file URL. +* It does no extension searching. A file extension must be provided + when the specifier is a relative or absolute file URL. * It does not support folders as modules, directory indexes (e.g. `'./startup/index.js'`) must be fully specified. * It can load JSON modules, but an import assertion is required (behind @@ -1275,11 +1276,11 @@ This field defines [subpath imports][] for the current package. [`--conditions` / `-C` flag]: #resolving-user-conditions [`--no-addons` flag]: cli.md#--no-addons [`ERR_PACKAGE_PATH_NOT_EXPORTED`]: errors.md#err_package_path_not_exported -[`ERR_REQUIRE_ESM`]: errors.md#err_require_esm [`esm`]: https://github.com/standard-things/esm#readme [`package.json`]: #nodejs-packagejson-field-definitions [entry points]: #package-entry-points [folders as modules]: modules.md#folders-as-modules +[load ECMASCript modules from CommonJS modules]: modules.md#the-mjs-extension [loader hooks]: esm.md#loaders [self-reference]: #self-referencing-a-package-using-its-name [subpath exports]: #subpath-exports From fe05b7283fcb1c2037bc962cddf66e492371a0a3 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Fri, 14 Jan 2022 20:47:32 +0100 Subject: [PATCH 12/14] fixup! --- doc/api/packages.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index 48acc6905c8b14..e75549256bf2fc 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -94,9 +94,10 @@ There is the CommonJS module loader: * It is fully synchronous. * It is responsible for handling `require()` calls. * It is monkey patchable. -* When resolving a specifier, if no exact match is found, it will try to add - extensions (`.js`, `.json`, and finally `.node`). * It supports [folders as modules][]. +* When resolving a specifier, if no exact match is found, it will try to add + extensions (`.js`, `.json`, and finally `.node`) and then attempt to resolve + [folders as modules][]. * It treats `.json` as JSON text files. * `.node` files are interpreted as compiled addon modules loaded with `process.dlopen()`. @@ -112,10 +113,10 @@ There is the ECMAScript module loader: * It is asynchronous. * It is responsible for handling `import` statements and `import()` expressions. * It is not monkey patchable, can be customized using [loader hooks][]. -* It does no extension searching. A file extension must be provided - when the specifier is a relative or absolute file URL. * It does not support folders as modules, directory indexes (e.g. `'./startup/index.js'`) must be fully specified. +* It does no extension searching. A file extension must be provided + when the specifier is a relative or absolute file URL. * It can load JSON modules, but an import assertion is required (behind `--experimental-json-modules` flag). * It accepts only `.js`, `.mjs`, and `.cjs` extensions for JavaScript text From 5de669805cea6f710dbb36760a189dff53179b2b Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Sun, 16 Jan 2022 18:57:08 +0100 Subject: [PATCH 13/14] fixup! --- doc/api/cli.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/api/cli.md b/doc/api/cli.md index 9aa94b26d2fea1..e44ceb23cb2bf5 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -31,11 +31,12 @@ corresponding file is found, an error is thrown. If a file is found, its path will be passed to the [ECMAScript module loader][] under any of the following conditions: +* The program was started with a command-line flag that forces the entry + point to be loaded with ECMAScript module loader. * The file has an `.mjs` extension. +* The file does not have a `.cjs` extension. * The file nearest parent `package.json` file contains a top-level [`"type"`][] field with a value of `"module"`. -* If the program was started with a command-line flag that forces the entry - point to be loaded with ECMAScript module loader. Otherwise, the file is loaded using the CommonJS module loader. See [Modules loaders][] for more details. From b08ec87094316e0d9e60931f2d8bae4a100e8815 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Sun, 16 Jan 2022 18:59:25 +0100 Subject: [PATCH 14/14] fixup! --- doc/api/cli.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/api/cli.md b/doc/api/cli.md index e44ceb23cb2bf5..faed84f3f520ae 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -34,9 +34,9 @@ under any of the following conditions: * The program was started with a command-line flag that forces the entry point to be loaded with ECMAScript module loader. * The file has an `.mjs` extension. -* The file does not have a `.cjs` extension. -* The file nearest parent `package.json` file - contains a top-level [`"type"`][] field with a value of `"module"`. +* The file does not have a `.cjs` extension, and the nearest parent + `package.json` file contains a top-level [`"type"`][] field with a value of + `"module"`. Otherwise, the file is loaded using the CommonJS module loader. See [Modules loaders][] for more details.