Neverending Plethora of Modules
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

esm

3.0.71 • Public • Published

esm

A fast, production ready, zero-dependency ES module loader for Node 6+!

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

Install

  • New projects

    Run npm init esm or yarn create esm.

    💡 Use the -y flag to answer “yes” to all prompts.

  • Existing projects

    Run npm i esm or yarn add esm.

Getting started

There are two ways to enable esm.

  1. Enable esm for packages:

    Use esm to load the main ES module and export it as CommonJS.

    index.js

    // Set options as a parameter, environment variable, or rc file.
    require = require("esm")(module/*, options*/)
    module.exports = require("./main.js")

    main.js

    // ESM syntax is supported.
    export {}

    💡 These files are automagically created with npm init esm or yarn create esm.

  2. Enable esm for local runs:

    node -r esm main.js

    💡 Omit the filename to enable esm in the REPL.

Features

The esm loader bridges the ESM of today to the ESM of tomorrow.

👏 By default, 💯 percent CJS interoperability is enabled so you can get stuff done fast.
🔒 .mjs files are limited to basic functionality without support for esm options.

Out of the box esm just works, no configuration necessary, and supports:

Options

Specify options with one of the following:

  • The "esm" field in 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

{
"await":

A boolean for top-level await in modules without ESM exports.

"cjs":

A boolean or object for toggling CJS features in ESM.

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.

"mutableNamespace":

A boolean for mutable namespace objects.

"namedExports":

A boolean for importing named exports of CJS modules.

"paths":

A boolean for following CJS path rules in ESM.

"vars":

A boolean for __dirname, __filename, and require in ESM.

}
"force":

A boolean to apply these options to all module loads.

"mainFields":

An array of fields, e.g. ["main"], checked when importing a package.

"mode":

A string mode:

  • "auto" detect files with import, import.meta, export,
    "use module", or .mjs as ESM
  • "all" script files are treated as ESM
  • "strict" to treat only .mjs files as ESM
}

DevOpts

{
"cache":

A boolean for toggling cache creation or cache directory path.

"debug":

A boolean for unmasking methods and stack traces.

"sourceMap":

A boolean for including inline source maps.

}

Tips

📦 Bundling

  • Add a “module” field to package.json with the path to the main ES module.

    💡 This is automagically done with npm init esm or yarn create esm.

  • Use esmify with browserify.

🔧 Extensions

🚚 Loading

  • The jasmine test runner does not have a mechanism to load esm. However, esm can load a bootstrap file that programmaticly runs tests following their library usage example.

  • Load esm before APMs/loaders like @babel/register, newrelic, and sqreen.

  • Load esm with the “node-args” options of

    • node-tap: --node-arg=-r --node-arg=esm
    • pm2: --node-args="-r esm"
  • Load esm with “require” options of ava, mocha, nodemon, nyc, qunit, tape, ts-node, and webpack.

    🎗 When using a package’s “require” option remember that, per Node’s rules, the builtin require function cannot sideload .mjs files. However, with esm, ES modules can be sideloaded as .js files or .mjs files can be loaded with dynamic import.

install

npm i esm

Downloadsweekly downloads

32,132

version

3.0.71

license

MIT

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar