Awesome

esm

The brilliantly simple, babel-less, bundle-less ECMAScript module loader.

esm is the world’s most advanced ECMAScript module loader. This fast, production ready, zero dependency loader is all you need to support ECMAScript modules in Node 6+. See the release post and video for details!

Install

New projects

Run npm init esm or yarn create esm.

:bulb: Use the -y flag to answer “yes” to all prompts.
Existing projects

Run npm i esm or yarn add esm.

Getting started

There are two ways to enable esm.

Enable esm for packages:

Use esm to load the main ES module and export it as CommonJS.

index.js

// Set options as a parameter, environment variable, or rc file.
require = require("esm")(module/*, options*/)
module.exports = require("./main.js")

main.js

// ESM syntax is supported.
export {}

:bulb: These files are automagically created with npm init esm or yarn create esm.

Enable esm for local runs:
```
node -r esm main.js
```
:bulb: Omit the filename to enable esm in the REPL.

Features

:clap: By default, :100: percent CJS interoperability is enabled so you can get stuff done. :lock: .mjs files are limited to basic functionality without support for esm options.

Out of the box esm just works, no configuration necessary, and supports:

Passing all applicable test262 compliance tests
import/export
import.meta
Dynamic import
Live bindings
File URI scheme
Node stdin, --eval, --print flags
Node --check flag (Node 10+)

Options

Specify options with one of the following:

"esm" field in package.json
CJS/ESM in an .esmrc.js, .esmrc.cjs, or .esmrc.mjs file
JSON6 in an .esmrc or .esmrc.json file
JSON6 or file path in the ESM_OPTIONS environment variable
ESM_DISABLE_CACHE environment variable

<table> <tr> <td colspan="2"><code>{</code></td> </tr> <tr> <td valign="top"><code>"cjs":true</code></td> <td> A boolean or object for toggling CJS features in ESM. <details> <summary>Features</summary> <table> <tr> <td colspan="2"><code>{</code></td> </tr> <tr> <td valign="top"><code>"cache":true</code></td> <td> A boolean for storing ES modules in <code>require.cache</code>. </td> </tr> <tr> <td valign="top"><code>"esModule":true</code></td> <td> A boolean for <code>__esModule</code> interoperability. </td> </tr> <tr> <td valign="top"><code>"extensions":true</code></td> <td> A boolean for respecting <code>require.extensions</code> in ESM. </td> </tr> <tr> <td valign="top"><code>"mutableNamespace":true</code></td> <td> A boolean for mutable <a href="https://ponyfoo.com/articles/es6-modules-in-depth#import-all-the-things">namespace objects</a>. </td> </tr> <tr> <td valign="top"><code>"namedExports":true</code></td> <td> A boolean for <a href="https://ponyfoo.com/articles/es6-modules-in-depth#importing-named-exports">importing named exports</a> of CJS modules. </td> </tr> <tr> <td valign="top"><code>"paths":true</code></td> <td> 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. </td> </tr> <tr> <td valign="top"><code>"vars":true</code></td> <td> A boolean for <code>__dirname</code>, <code>__filename</code>, and <code>require</code> in ESM. </td> </tr> <tr> <td valign="top"><code>"dedefault":false</code></td> <td> A boolean for requiring ES modules without the dangling <code>require().default</code>. </td> </tr> <tr> <td valign="top"><code>"topLevelReturn":false</code></td> <td> A boolean for top-level <code>return</code> support. </td> </tr> <tr> <td colspan="2"><code>}</code></td> </tr> </table> </details> </td> </tr> <tr> <td valign="top"><code>"mainFields":["main"]</code></td> <td> An array of fields checked when importing a package. </td> </tr> <tr> <td valign="top"><code>"mode":"auto"</code></td> <td> A string mode: <ul> <li><code>"auto"</code> detect files with <code>import</code>, <code>import.meta</code>, <code>export</code>, <a href="https://github.com/tc39/proposal-modules-pragma"><code>"use module"</code></a>, or <code>.mjs</code> as ESM.</li> <li><code>"all"</code> files besides those with <code>"use script"</code> or <code>.cjs</code> are treated as ESM.</li> <li><code>"strict"</code> to treat only <code>.mjs</code> files as ESM.</li> </ul> </td> </tr> <tr> <td valign="top"><code>"await":false</code></td> <td> A boolean for <a href="https://github.com/tc39/proposal-top-level-await">top-level <code>await</code></a> in modules without ESM exports. (Node 10+) </td> </tr> <tr> <td valign="top"><code>"force":false</code></td> <td> A boolean to apply these options to all module loads. </td> </tr> <tr> <td valign="top"><code>"wasm":false</code></td> <td> A boolean for <a href="https://nodejs.org/api/globals.html#globals_webassembly">WebAssembly</a> module support. (Node 8+) </td> </tr> <tr> <td colspan="2"><code>}</code></td> </tr> </table>

DevOpts

<table> <tr> <td colspan="2"><code>{</code></td> </tr> <tr> <td valign="top"><code>"cache":true</code></td> <td> A boolean for toggling cache creation or a cache directory path. </td> </tr> <tr> <td valign="top"><code>"sourceMap":false</code></td> <td> A boolean for including inline source maps. </td> </tr> <tr> <td colspan="2"><code>}</code></td> </tr> </table>

Tips

Bundling

For bundlers like browserify+esmify, parcel-bundler, and webpack add a "module" field to package.json pointing to the main ES module.
```
"main": "index.js",
"module": "main.js"
```
:bulb: This is automagically done with npm init esm or yarn create esm.

Extensions

Enable esm for wallaby.js following their integration example.

Loading

Load esm before loaders/monitors like @babel/register, newrelic, sqreen, and ts-node.
Load esm for jasmine using the "helpers" field in jasmine.json:
```
"helpers": [
  "node_modules/esm"
]
```
Load esm with “node-args" options of: 
- pm2: --node-args="-r esm"
Load esm with “require” options of ava, mocha, nodemon, nyc, qunit, tape, and webpack.

:bulb: Builtin require cannot sideload .mjs files. However, .js files can be sideloaded or .mjs files may be loaded with dynamic import.