** Note: This is a fork of the original ESM with the PR to update acorn**
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!
-
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.
👏 By default, 💯 percent CJS interoperability is enabled so you can get stuff done.
🔒 .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
,.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
{ |
|||||||||||||||||||||||
"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+) |
||||||||||||||||||||||
} |
{ |
|
"cache":true |
A boolean for toggling cache creation or a cache directory path. |
"sourceMap":false |
A boolean for including inline source maps. |
} |
-
For bundlers like
browserify
+esmify
,parcel-bundler
, andwebpack
add a"module"
field topackage.json
pointing to the main ES module."main": "index.js", "module": "main.js"
💡 This is automagically done with
npm init esm
oryarn create esm
.
- Enable
esm
forwallaby.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:pm2
:--node-args="-r esm"
-
Load
esm
with “require” options ofava
,mocha
,nodemon
,nyc
,qunit
,tape
, andwebpack
.💡 Builtin
require
cannot sideload.mjs
files. However,.js
files can be sideloaded or.mjs
files may be loaded with dynamicimport
.