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
require = require("esm")(module)
module.exports = require("./main.js")
main.js
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:
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
{ |
"cjs":true |
A boolean or object for toggling CJS features in ESM.
Features
{ | "cache":true |
A boolean for storing ES modules in require.cache .
| "esModule":true |
A boolean for __esModule interoperability.
| "extensions":true |
A boolean for respecting require.extensions in ESM.
| "mutableNamespace":true |
A boolean for mutable namespace objects.
| "namedExports":true |
A boolean for importing named exports of CJS modules.
| "paths":true |
A boolean for following CJS path rules in ESM.
| "vars":true |
A boolean for __dirname , __filename , and require in ESM.
| "dedefault":false |
A boolean for requiring ES modules without the dangling require().default .
| "topLevelReturn":false |
A boolean for top-level return support.
| } |
|
"mainFields":["main"] |
An array of fields checked when importing a package.
|
"mode":"auto" |
A string mode:
"auto" detect files with import , import.meta , export ,
"use module" , or .mjs as ESM."all" files besides those with "use script" or .cjs are treated as ESM."strict" to treat only .mjs files as ESM.
|
"await":false |
A boolean for top-level await in modules without ESM exports. (Node 10+)
|
"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
, 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
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
.