@std/esm
This fast, small, zero-dependency package is all you need to enable
ES modules in Node 6+ today!
See the release post
:book: and video :movie_camera:
for all the details.
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
require = require("@std/esm")(module)
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.
:point_right: This means, by default, ESM requires the use of the .mjs
file
extension.
:unlock: You can unlock ESM with the .js
file extension using
the "js"
ESM mode.
Out of the box @std/esm
just works, no configuration necessary, and supports:
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: "all" files as ESM"js" and other files with import , import.meta , export , or "use module" as ESM
|
"cjs": | A boolean or object to unlock CJS features in ESM. Unlockable Features{ | "cache": | A boolean for storing ES modules in require.cache . | "extensions": | A boolean for respecting require.extensions in ESM. | "interop": | A boolean for __esModule interoperability. | "namedExports": | A boolean for importing named exports of CJS modules. | "paths": | A boolean for following CJS path rules in ESM. | "topLevelReturn": | A boolean for top-level return . | "vars": | A boolean for __dirname , __filename , and require in ESM. | } |
|
"await": | A boolean for top-level await in modules without ESM exports. (requires Node 7.6+) |
} |
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 of
ava
,
mocha
,
nyc
, and
tape
- Load
@std/esm
with the --node-arg=-r --node-arg=@std/esm
option of
node-tap
- Load
@std/esm
with the --node-args="-r @std/esm"
option of
pm2
- Load
@std/esm
with wallaby.js
- Use
@std/esm
to load jasmine
- Use
"@std/esm":"cjs"
for the --watch
and --watch-extensions
options of
mocha
- Use
"@std/esm":"cjs"
for ava
and webpack
- When in doubt, use
"@std/esm":"cjs"