fixup!

nodejs · Jan 8, 2022 · ce3edd0 · ce3edd0
1 parent c19d161
commit ce3edd0
Show file tree

Hide file tree

Showing 3 changed files with 41 additions and 3 deletions.
diff --git 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
@@ -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
@@ -3,4 +3,4 @@
     "command line options": "cli.html#options",
     "web server": "http.html"
   }
-}
+}
-Original file line number
+Diff line change
@@ Expand Up / @@ -3,4 +3,4 @@ @@
         "command line options": "cli.html#options",
         "web server": "http.html"
       }
-    }
+    }