A fast, production ready, zero-dependency ES module loader for Node 6+!
See the release post and video for all the details.
-
New projects
Run
npm init esm
oryarn create esm
.đź’ˇ Use the
-y
flag to answer “yes” to all prompts. -
Existing projects
Run
npm i esm
oryarn add esm
.
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 {}
đź’ˇ These files are automagically created with
npm init esm
oryarn create esm
. -
Enable
esm
for local runs:node -r esm main.js
đź’ˇ Omit the filename to enable
esm
in the REPL.
The esm
loader bridges the ESM of today to the
ESM of tomorrow.
đź‘Ź By default, đź’Ż percent CJS interoperability is enabled so you can get stuff done fast.
đź”’ .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+)
Specify options with one of the following:
"esm"
field inpackage.json
- CJS/ESM in an
.esmrc.js
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
{ |
|||||||||||||||||||
"await": |
A boolean for top-level |
||||||||||||||||||
"cjs": |
A boolean or object for toggling CJS features in ESM. Features
|
||||||||||||||||||
"force": |
A boolean to apply these options to all module loads. |
||||||||||||||||||
"mainFields": |
An array of fields, e.g. |
||||||||||||||||||
"mode": |
A string mode:
|
||||||||||||||||||
"wasm": |
A boolean for WebAssembly module support. (Node 8+) |
||||||||||||||||||
} |
{ |
|
"cache": |
A boolean for toggling cache creation or cache directory path. |
"sourceMap": |
A boolean for including inline source maps. |
} |
-
Add a “module” field to
package.json
with the path to the main ES module.đź’ˇ This is automagically done with
npm init esm
oryarn create esm
. -
Use
esmify
withbrowserify
.
- Enable ESM syntax for
wallaby.js
following their integration example.
-
Load
esm
before loaders/monitors like@babel/register
,newrelic
,sqreen
, andts-node
. -
Load
esm
forjasmine
using the “helpers” field injasmine.json
:"helpers": [ "node_modules/esm" ]
-
Load
esm
with “node-args" options of: -
Load
esm
with “require” options ofava
,mocha
,nodemon
,nyc
,qunit
,tape
, andwebpack
.💡 By Node’s rules, builtin
require
cannot sideload.mjs
files. However, withesm
, ES modules can be sideloaded as.js
files or.mjs
files may be loaded with dynamicimport
.