esm
The brilliantly simple, babel-less, bundle-less ECMAScript module loader.
esmis 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 esmoryarn create esm.💡 Use the-yflag to answer “yes” to all prompts. -
Existing projects
Run
npm i esmoryarn add esm.
Getting started
There are two ways to enable esm.
-
Enable
esmfor packages:Use
esmto 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 withnpm init esmoryarn create esm. -
Enable
esmfor local runs:node -r esm main.js
💡 Omit the filename to enableesmin the REPL.
Features
.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/exportimport.meta- Dynamic
import - Live bindings
- File URI scheme
- Node
stdin,--eval,--printflags - Node
--checkflag (Node 10+)
Options
Specify options with one of the following:
"esm"field inpackage.json- CJS/ESM in an
.esmrc.js,.esmrc.cjs, or.esmrc.mjsfile - JSON6 in an
.esmrcor.esmrc.jsonfile - JSON6 or file path in the
ESM_OPTIONSenvironment variable ESM_DISABLE_CACHEenvironment variable
{ |
|||||||||||||||||||||||
"cjs":true |
A boolean or object for toggling CJS features in ESM. Features
|
||||||||||||||||||||||
"mainFields":["main"] |
An array of fields checked when importing a package. |
||||||||||||||||||||||
"mode":"auto" |
A string mode:
|
||||||||||||||||||||||
"await":false |
A boolean for top-level |
||||||||||||||||||||||
"force":false |
A boolean to apply these options to all module loads. |
||||||||||||||||||||||
"wasm":false |
A boolean for WebAssembly module support. (Node 8+) |
||||||||||||||||||||||
} |
|||||||||||||||||||||||
DevOpts
{ |
|
"cache":true |
A boolean for toggling cache creation or a cache directory path. |
"sourceMap":false |
A boolean for including inline source maps. |
} |
|
Tips
Bundling
-
For bundlers like
browserify+esmify,parcel-bundler, andwebpackadd a"module"field topackage.jsonpointing to the main ES module."main": "index.js", "module": "main.js"
💡 This is automagically done withnpm init esmoryarn create esm.
Extensions
- Enable
esmforwallaby.jsfollowing their integration example.
Loading
-
Load
esmbefore loaders/monitors like@babel/register,newrelic,sqreen, andts-node. -
Load
esmforjasmineusing the"helpers"field injasmine.json:"helpers": [ "node_modules/esm" ]
-
Load
esmwith “node-args" options of:pm2:--node-args="-r esm"
-
Load
esmwith “require” options ofava,mocha,nodemon,nyc,qunit,tape, andwebpack.💡 Builtinrequirecannot sideload.mjsfiles. However,.jsfiles can be sideloaded or.mjsfiles may be loaded with dynamicimport.