summaryrefslogtreecommitdiff
path: root/doc/api/esm.md
diff options
context:
space:
mode:
authorBradley Farias <bradley.meck@gmail.com>2017-06-05 19:44:56 -0500
committerBradley Farias <bradley.meck@gmail.com>2017-09-07 15:18:32 -0500
commitc8a389e19f172edbada83f59944cad7cc802d9d5 (patch)
tree15a8653683a97ff0d6b2e7f08ef8081405700ea3 /doc/api/esm.md
parent46133b5beba2c780fb3b9a9d6be610d09f752182 (diff)
downloadandroid-node-v8-c8a389e19f172edbada83f59944cad7cc802d9d5.tar.gz
android-node-v8-c8a389e19f172edbada83f59944cad7cc802d9d5.tar.bz2
android-node-v8-c8a389e19f172edbada83f59944cad7cc802d9d5.zip
module: Allow runMain to be ESM
This follows the EPS an allows the node CLI to have ESM as an entry point. `node ./example.mjs`. A newer V8 is needed for `import()` so that is not included. `import.meta` is still in specification stage so that also is not included. PR-URL: https://github.com/nodejs/node/pull/14369 Author: Bradley Farias <bradley.meck@gmail.com> Author: Guy Bedford <guybedford@gmail.com> Author: Jan Krems <jan.krems@groupon.com> Author: Timothy Gu <timothygu99@gmail.com> Author: Michaƫl Zasso <targos@protonmail.com> Author: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Diffstat (limited to 'doc/api/esm.md')
-rw-r--r--doc/api/esm.md88
1 files changed, 88 insertions, 0 deletions
diff --git a/doc/api/esm.md b/doc/api/esm.md
new file mode 100644
index 0000000000..108fd76336
--- /dev/null
+++ b/doc/api/esm.md
@@ -0,0 +1,88 @@
+# ECMAScript Modules
+
+<!--introduced_in=v9.x.x-->
+
+> Stability: 1 - Experimental
+
+<!--name=esm-->
+
+Node contains support for ES Modules based upon the [the Node EP for ES Modules][].
+
+Not all features of the EP are complete and will be landing as both VM support and implementation is ready. Error messages are still being polished.
+
+## Enabling
+
+<!-- type=misc -->
+
+The `--experimental-modules` flag can be used to enable features for loading ESM modules.
+
+Once this has been set, files ending with `.mjs` will be able to be loaded as ES Modules.
+
+```sh
+node --experimental-modules my-app.mjs
+```
+
+## Features
+
+<!-- type=misc -->
+
+### Supported
+
+Only the CLI argument for the main entry point to the program can be an entry point into an ESM graph. In the future `import()` can be used to create entry points into ESM graphs at run time.
+
+### Unsupported
+
+| Feature | Reason |
+| --- | --- |
+| `require('./foo.mjs')` | ES Modules have differing resolution and timing, use language standard `import()` |
+| `import()` | pending newer V8 release used in Node.js |
+| `import.meta` | pending V8 implementation |
+| Loader Hooks | pending Node.js EP creation/consensus |
+
+## Notable differences between `import` and `require`
+
+### No NODE_PATH
+
+`NODE_PATH` is not part of resolving `import` specifiers. Please use symlinks if this behavior is desired.
+
+### No `require.extensions`
+
+`require.extensions` is not used by `import`. The expectation is that loader hooks can provide this workflow in the future.
+
+### No `require.cache`
+
+`require.cache` is not used by `import`. It has a separate cache.
+
+### URL based paths
+
+ESM are resolved and cached based upon [URL](url.spec.whatwg.org) semantics. This means that files containing special characters such as `#` and `?` need to be escaped.
+
+Modules will be loaded multiple times if the `import` specifier used to resolve them have a different query or fragment.
+
+```js
+import './foo?query=1'; // loads ./foo with query of "?query=1"
+import './foo?query=2'; // loads ./foo with query of "?query=2"
+```
+
+For now, only modules using the `file:` protocol can be loaded.
+
+## Interop with existing modules
+
+All CommonJS, JSON, and C++ modules can be used with `import`.
+
+Modules loaded this way will only be loaded once, even if their query or fragment string differs between `import` statements.
+
+When loaded via `import` these modules will provide a single `default` export representing the value of `module.exports` at the time they finished evaluating.
+
+```js
+import fs from 'fs';
+fs.readFile('./foo.txt', (err, body) => {
+ if (err) {
+ console.error(err);
+ } else {
+ console.log(body);
+ }
+});
+```
+
+[the Node EP for ES Modules]: https://github.com/nodejs/node-eps/blob/master/002-es-modules.md