@std/esm
This fast, small, zero-dependency package is all you need to enable
ES modules in Node 4+ 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.
-
Create the ESM loader to import your main ES module:
index.js
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 file.mjs
Enable ESM in the Node REPL:
node -r @std/esm
Or upon entering:
$ node
> require("@std/esm")
@std/esm enabled
> import p from "path"
undefined
> p.join("hello", "world")
'hello/world'
Note: The "cjs"
and "gz"
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 extra 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":{"esm":"js"}
"@std/esm":"cjs"
is shorthand for "@std/esm":{"cjs":true,"esm":"js"}
{
|
"esm": |
A string ESM mode:
"mjs" files as ESM (default)"all" files as ESM"js" and other files with import , export , or "use module" as ESM"cjs" shorthand for "@std/esm":{"cjs":true,"esm":"js"}
|
"cjs": |
A boolean to unlock CJS features in ESM.
|
"await": |
A boolean to support top-level await in the main module (requires Node 7.6+).
|
"gz": |
A boolean to support gzipped module (i.e. .js.gz , .mjs.gz ).
Note: Don’t forget the webpack gzip-loader .
|
}
|
Cont’d
The "cjs"
option may also be specified as an object.
{
"cjs": {
|
"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 to support importing named exports of CJS modules.
|
"paths": |
A boolean for following CJS path rules in ESM.
|
"topLevelReturn": |
A boolean to support top-level return .
|
"vars": |
A boolean to expose __dirname , __filename , and require in ESM.
|
}
}
|
DevOpts
{
|
"cache": |
A boolean for toggling .cache creation (default: true ).
|
"debug": |
A boolean for unmasking stack traces.
|
"sourceMap": |
A boolean for including inline source maps.
Note: Automatically enabled using the Node CLI
--inspect option.
|
"warnings": |
A boolean for logging parse and runtime warnings.
(default: process.env.NODE_ENV !== "production" )
|
}
|
Tips
- Load
@std/esm
before
@babel/register
v7+ - Load
@std/esm
with the “require” option of
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
- Use
"@std/esm":"cjs"
with the --watch
and --watch-extensions
options of
mocha
- Use
"@std/esm":"cjs"
with webpack
- When in doubt, use
"@std/esm":"cjs"