@std/esm
This fast, small, zero-dependency package is all you need to enable ES modules in Node 6+ today!
See the release post
Discontinued
This package has been discontinued in favor of esm
.
Getting started
Run npm i --save @std/esm
in your app or package directory.
There are three ways to enable ESM with @std/esm
.
-
Enable ESM with a CJS bridge:
index.js
// Provide options as a parameter, environment variable, or rc file. require = require("@std/esm")(module/*, options*/) module.exports = require("./main.mjs").default
-
Enable ESM in the Node CLI with the
-r
option:node -r @std/esm main.mjs
-
Enable ESM in the Node REPL:
node -r @std/esm
or upon entering:
$ node > require("@std/esm") @std/esm enabled
Note: All "cjs"
options are unlocked in the Node REPL.
Standard Features
The @std/esm
loader is as spec-compliant
as possible and follows Node’s ESM rules.
.mjs
file
extension.
.js
file extension using
the "js"
ESM mode.
Out of the box @std/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
"@std/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:
-
"@std/esm":"js"
is shorthand for"@std/esm":{"mode":"js"}
-
"@std/esm":"cjs"
is shorthand for"@std/esm":{"cjs":true,"mode":"js"}
{ | |||||||||||||||||||
"mode": |
A string mode:
|
||||||||||||||||||
"cjs": |
A boolean or object to unlock CJS features in ESM. A boolean for storing ES modules in A boolean for respecting A boolean for A boolean for importing named exports of CJS modules. A boolean for following CJS path rules in ESM. A boolean for top-level A boolean for |
||||||||||||||||||
"await": |
A boolean for top-level |
||||||||||||||||||
} |
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
@std/esm
before@babel/register
v7+ - Load
@std/esm
with the “require” option ofava
,mocha
,nyc
, andtape
- Load
@std/esm
with the--node-arg=-r --node-arg=@std/esm
option ofnode-tap
- Load
@std/esm
with the--node-args="-r @std/esm"
option ofpm2
- Load
@std/esm
withwallaby.js
- Use
@std/esm
to loadjasmine
- Use
"@std/esm":"cjs"
for the--watch
and--watch-extensions
options ofmocha
- Use
"@std/esm":"cjs"
forava
andwebpack
- When in doubt, use
"@std/esm":"cjs"