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