@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.

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.

: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.

<summary>Unlockable Features</summary>

`{`
`"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"

Current Tags

0.26.0 ... latest (8 years ago)