/esm

Tomorrow's ECMAScript modules today!

Primary LanguageJavaScriptOtherNOASSERTION

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 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.
}
"mainFields":

An array of fields, e.g. ["main"], to check 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 string path of the cache directory.
"debug":

A boolean for unmasking methods and stack traces.
"sourceMap":

A boolean for including inline source maps.
"warnings":

A boolean for logging development parse and runtime warnings.
}

Tips