doc: phase 2 documentation

Co-authored-by: Myles Borins <[email protected]>
Co-authored-by: Evan Plaice <[email protected]>
Co-authored-by: James M Snell <[email protected]>

Author: 4 people

doc/api/cli.md

@@ -134,6 +134,27 @@ added: v6.0.0
 Enable FIPS-compliant crypto at startup. (Requires Node.js to be built with
 `./configure --openssl-fips`.)
 
+### `--es-module-specifier-resolution=mode`
+<!-- YAML
+added: REPLACEME
+-->
+
+To be used in conjunction with `--experimental modules`. Sets the resolution
+algorithm for resolving specifiers. Valid options are `explicit` and `node`.
+
+The default is `explicit`, which requires providing the full path to a
+module. The `node` mode will enable support for optional file extensions and
+the ability to import a directory that has an index file.
+
+Please see [customizing esm specifier resolution][] for example usage.
+
+### `--experimental-json-modules`
+<!-- YAML
+added: REPLACEME
+-->
+
+Enable experimental JSON support for the ES Module loader.
+
 ### `--experimental-modules`
 <!-- YAML
 added: v8.5.0
@@ -511,17 +532,16 @@ added: v2.4.0
 
 Track heap object allocations for heap snapshots.
 
-### `-m`, `--type=type`
+### `--type=type`
 
-When using `--experimental-modules`, this informs the module resolution type
-to interpret the top-level entry into Node.js.
+Used with `--experimental-modules`, this configures Node.js to interpret the
+initial entry point as CommonJS or as an ES module.
 
-Works with stdin, `--eval`, `--print` as well as standard execution.
+Valid values are `"commonjs"` and `"module"`. The default is to infer from
+the file extension and the `"type"` field in the nearest parent `package.json`.
 
-Valid values are `"commonjs"` and `"module"`, where the default is to infer
-from the file extension and package type boundary.
+Works for executing a file as well as `--eval`, `--print`, `STDIN`.
 
-`-m` is an alias for `--type=module`.
 
 ### `--use-bundled-ca`, `--use-openssl-ca`
 <!-- YAML
@@ -916,7 +936,8 @@ greater than `4` (its current default value). For more information, see the
 [debugger]: debugger.html
 [debugging security implications]: https://nodejs.org/en/docs/guides/debugging-getting-started/#security-implications
 [emit_warning]: process.html#process_process_emitwarning_warning_type_code_ctor
-[experimental ECMAScript Module]: esm.html#esm_experimental_loader_hooks
+[experimental ECMAScript Module]: esm.html#esm_resolve_hook
+[customizing esm specifier resolution]: esm.html#esm_customizing_esm_specifier_resolution_algorithm
 [libuv threadpool documentation]: http://docs.libuv.org/en/latest/threadpool.html
 [remote code execution]: https://www.owasp.org/index.php/Code_Injection
 [secureProtocol]: tls.html#tls_tls_createsecurecontext_options