1 | # @std/esm
|
2 |
|
3 | This fast, small, zero-dependency package is all you need to enable
|
4 | ES modules in Node 4+ today!
|
5 |
|
6 | See the release [post](https://medium.com/web-on-the-edge/es-modules-in-node-today-32cff914e4b)
|
7 | :book: and [video](https://www.youtube.com/watch?v=60S1PFndbn0) :movie_camera:
|
8 | for all the details.
|
9 |
|
10 | Getting started
|
11 | ---
|
12 |
|
13 | Run `npm i --save @std/esm` in your app or package directory.
|
14 |
|
15 | There are three ways to enable ESM with `@std/esm`.
|
16 |
|
17 | 1. Enable ESM with a CJS bridge:
|
18 |
|
19 | **index.js**
|
20 | ```js
|
21 | // Provide options as a parameter, environment variable, or rc file.
|
22 | require = require("@std/esm")(module/*, options*/)
|
23 | module.exports = require("./main.mjs").default
|
24 | ```
|
25 |
|
26 | 2. Enable ESM in the Node CLI with the [`-r` option](https://nodejs.org/api/cli.html#cli_r_require_module):
|
27 |
|
28 | ```shell
|
29 | node -r @std/esm main.mjs
|
30 | ```
|
31 |
|
32 | 3. Enable ESM in the Node REPL:
|
33 |
|
34 | ```shell
|
35 | node -r @std/esm
|
36 | ```
|
37 |
|
38 | or upon entering:
|
39 |
|
40 | ```shell
|
41 | $ node
|
42 | > require("@std/esm")
|
43 | @std/esm enabled
|
44 | ```
|
45 |
|
46 | *Note: All `"cjs"` options are [unlocked](#unlockables) in the Node REPL.*
|
47 |
|
48 | Standard Features
|
49 | ---
|
50 |
|
51 | The `@std/esm` loader is as spec-compliant
|
52 | as possible and follows Node’s [ESM rules](https://github.com/nodejs/node-eps/blob/master/002-es-modules.md).
|
53 |
|
54 | :point_right: This means, by default, ESM requires the use of the `.mjs` file
|
55 | extension.<br>
|
56 | :unlock: You can [unlock](#unlockables) ESM with the `.js` file extension using
|
57 | the `"js"` ESM mode.
|
58 |
|
59 | Out of the box `@std/esm` just works, no configuration necessary, and supports:
|
60 |
|
61 | * [`import`](https://ponyfoo.com/articles/es6-modules-in-depth#import) / [`export`](https://ponyfoo.com/articles/es6-modules-in-depth#export)
|
62 | * [`import.meta`](https://github.com/tc39/proposal-import-meta)
|
63 | * [Dynamic `import`](https://github.com/tc39/proposal-dynamic-import)
|
64 | * [Improved errors](https://github.com/standard-things/esm/wiki/improved-errors)
|
65 | * [Live bindings](https://ponyfoo.com/articles/es6-modules-in-depth#bindings-not-values)
|
66 | * [Loading `.mjs` files as ESM](https://github.com/nodejs/node-eps/blob/master/002-es-modules.md#32-determining-if-source-is-an-es-module)
|
67 | * [The file URI scheme](https://en.wikipedia.org/wiki/File_URI_scheme)
|
68 | * Node 4+ support
|
69 |
|
70 | Unlockables
|
71 | ---
|
72 |
|
73 | Unlock features with options specified as one of the following:
|
74 |
|
75 | * The `"@std/esm"` field in your package.json
|
76 | * [JSON6](https://github.com/d3x0r/json6) in an .esmrc or .esmrc.json file
|
77 | * JSON6 or file path in the `ESM_OPTIONS` environment variable
|
78 | * CJS/ESM in an .esmrc.js or .esmrc.mjs file
|
79 |
|
80 | Commonly used options may be specified in shorthand form:
|
81 |
|
82 | * `"@std/esm":"js"` is shorthand for `"@std/esm":{"esm":"js"}`
|
83 | * `"@std/esm":"cjs"` is shorthand for `"@std/esm":{"cjs":true,"esm":"js"}`
|
84 |
|
85 | <table><tr><td colspan=2><code>{</code><tr><td valign=top><code>"esm":</code><td><p>A string mode:<ul><li><code>"all"</code> files as ESM<li><code>"js"</code> and other files with <code>import</code>, <code>import.meta</code>, <code>export</code>, or <a href=https://github.com/tc39/proposal-modules-pragma><code>"use module"</code></a> as ESM</ul><tr><td valign=top><code>"cjs":</code><td><p>A boolean or object to unlock CJS features in ESM.<details><summary>Unlockable Features</summary><table><tr><td colspan=2><code>{</code><tr><td valign=top><code>"cache":</code><td><p>A boolean for storing ES modules in <code>require.cache</code>.<tr><td valign=top><code>"extensions":</code><td><p>A boolean for respecting <code>require.extensions</code> in ESM.<tr><td valign=top><code>"interop":</code><td><p>A boolean for <code>__esModule</code> interoperability.<tr><td valign=top><code>"namedExports":</code><td><p>A boolean for <a href=https://ponyfoo.com/articles/es6-modules-in-depth#importing-named-exports>importing named exports</a> of CJS modules.<tr><td valign=top><code>"paths":</code><td><p>A boolean for following CJS <a href=https://github.com/nodejs/node-eps/blob/master/002-es-modules.md#432-removal-of-non-local-dependencies>path rules</a> in ESM.<tr><td valign=top><code>"topLevelReturn":</code><td><p>A boolean for <a href=http://stackoverflow.com/questions/28955047/why-does-a-module-level-return-statement-work-in-node-js/#28955050>top-level <code>return</code></a>.<tr><td valign=top><code>"vars":</code><td><p>A boolean for <code>__dirname</code>, <code>__filename</code>, and <code>require</code> in ESM.<tr><td colspan=2><code>}</code></table></details><tr><td valign=top><code>"await":</code><td><p>A boolean for top-level <code>await</code> in modules without ESM exports. <i>(requires Node 7.6+)</i><tr><td colspan=2><code>}</code></table>
|
86 |
|
87 | DevOpts
|
88 | ---
|
89 |
|
90 | <table><tr><td colspan=2><code>{</code><tr><td valign=top><code>"cache":</code><td><p>A boolean for toggling cache creation or string path of the cache directory.<tr><td valign=top><code>"debug":</code><td><p>A boolean for unmasking stack traces.<tr><td valign=top><code>"sourceMap":</code><td><p>A boolean for including inline source maps.<tr><td valign=top><code>"warnings":</code><td><p>A boolean for logging development parse and runtime warnings.<tr><td colspan=2><code>}</code></table>
|
91 |
|
92 | Tips
|
93 | ---
|
94 | * Load `@std/esm` before
|
95 | [`@babel/register`](https://github.com/babel/babel/tree/master/packages/babel-register) v7+
|
96 | * Load `@std/esm` with the *“require”* option of
|
97 | [`ava`](https://github.com/avajs/ava#options),
|
98 | [`mocha`](https://mochajs.org/#-r---require-module-name),
|
99 | [`nyc`](https://github.com/istanbuljs/nyc#require-additional-modules), and
|
100 | [`tape`](https://github.com/substack/tape#preloading-modules)
|
101 | * Load `@std/esm` with the `--node-arg=-r --node-arg=@std/esm` option of
|
102 | [`node-tap`](http://www.node-tap.org/cli/)
|
103 | * Load `@std/esm` with the `--node-args="-r @std/esm"` option of
|
104 | [`pm2`](http://pm2.keymetrics.io/docs/usage/quick-start/#options)
|
105 | * Load `@std/esm` with [`wallaby.js`](https://wallabyjs.com/docs/integration/node.html#es-modules)
|
106 | * Use `@std/esm` to load [`jasmine`](https://jasmine.github.io/setup/nodejs.html#a-simple-example-using-the-library)
|
107 | * Use `"@std/esm":"cjs"` for the `--watch` and `--watch-extensions` options of
|
108 | [`mocha`](https://mochajs.org/#-w---watch)
|
109 | * Use `"@std/esm":"cjs"` for [`ava`](https://github.com/avajs/ava) and [`webpack`](https://github.com/webpack/webpack)
|
110 | * When in doubt, use `"@std/esm":"cjs"`
|