node package manager
Orgs are free. Discover, share, and reuse code in your team. Create a free org »

@std/esm

@std/esm

This fast, small, zero-dependency package is all you need to enable ES modules in Node 4+ today!

See the release post 📖 and video 🎥 for all the details.

Getting started

  1. Run npm i --save @std/esm in your app or package directory.

  2. Create the ESM loader to import your main ES module:

    index.js

    require = require("@std/esm")(module)
    module.exports = require("./main.mjs").default

Enable processing all modules, including dependencies, by providing an options object or true to use the options from your .esmrc or package.json.

require = require("@std/esm")(module, options)

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.

👉 This means, by default, ESM requires the use of the .mjs file extension.
🔓 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 by specifying options in your .esmrc or "@std/esm" field of your package.json.

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

A boolean to unlock CJS features in ESM.

"await":

A boolean to support top-level await in the main ES module.

"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 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
  • Use "@std/esm":"cjs" or "@std/esm":{"cjs":{"cache":true}} with the Mocha --watch option
  • Use "@std/esm":"cjs" with webpack
  • When in doubt, use "@std/esm":"cjs"