esm

This fast, small, zero-dependency package is all you need to enable ES modules in Node 6+ today!

See the release post 📖 and video 🎥 for all the details.

Getting started

Run npm i --save esm in your app or package directory.

There are three ways to enable ESM with esm.

1. Enable ESM with a CJS bridge:

   index.js

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

2. Enable ESM in the Node CLI with the -r option:

   node -r esm main.mjs

3. Enable ESM in the Node REPL:

   node -r esm

   or upon entering:

   $ node
   > require("esm")
   esm enabled

Note: All "cjs" options are unlocked in the Node REPL.

Standard Features

The esm loader is as spec-compliant as possible and follows Node’s ESM rules.

👉 This means, by default, ESM requires the use of the .mjs file extension.
🔓 You can unlock ESM with the .js file extension using the "auto" ESM mode.

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

• import / export
• import.meta
• Dynamic import
• Improved errors
• Live bindings
• Loading .mjs files as ESM
• The file URI scheme
• Node --eval and --print flags
• Node 6+ support

Unlockables

Unlock features with options specified as one of the following:

• The "esm" field in your package.json
• JSON6 in an .esmrc or .esmrc.json file
• JSON6 or file path in the ESM_OPTIONS environment variable
• CJS/ESM in an .esmrc.js or .esmrc.mjs file

Commonly used options may be specified in shorthand form:

• "esm":"auto" is shorthand for "esm":{"mode":"auto"}
• "esm":"cjs" is shorthand for "esm":{"cjs":true,"mode":"auto"}

{
"mode":	A string mode: "all" files as ESM "auto" detect files with import, import.meta, export, or "use module" as ESM
"cjs":	A boolean or object to unlock CJS features in ESM. Unlockable Features { "cache": A boolean for storing ES modules in require.cache. "extensions": A boolean for respecting require.extensions in ESM. "interop": A boolean for __esModule interoperability. "namedExports": A boolean for importing named exports of CJS modules. "paths": A boolean for following CJS path rules in ESM. "topLevelReturn": A boolean for top-level return. "vars": A boolean for __dirname, __filename, and require in ESM. }
"await":	A boolean for top-level await in modules without ESM exports. (requires Node 7.6+)
}

DevOpts

{
"cache":	A boolean for toggling cache creation or string path of the cache directory.
"debug":	A boolean for unmasking stack traces.
"sourceMap":	A boolean for including inline source maps.
"warnings":	A boolean for logging development parse and runtime warnings.
}

Tips

• Load esm before @babel/register v7+
• Load esm with the “require” option of ava, mocha, nyc, and tape
• Load esm with the --node-arg=-r --node-arg=esm option of node-tap
• Load esm with the --node-args="-r esm" option of pm2
• Load esm with wallaby.js
• Use esm to load jasmine
• Use "esm":"cjs" for the --watch and --watch-extensions options of mocha
• Use "esm":"cjs" for ava and webpack
• When in doubt, use "esm":"cjs"