zkat / esm

Tomorrow's ECMAScript modules today!

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:

• import/export
• import.meta
• Dynamic import
• Improved errors
• Live bindings
• Loading .mjs files as ESM
• The file URI scheme
• Node --eval and --print flags
• Node --check flag (Node 10+)

Options

Specify options with one of the following:

• The "esm" field in package.json
• CJS/ESM in an .esmrc.js or .esmrc.mjs file
• JSON6 in an .esmrc or .esmrc.json file
• JSON6 or file path in the ESM_OPTIONS environment variable
• The ESM_DISABLE_CACHE environment variable

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

• Enable ESM syntax for wallaby.js following their integration example.

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 loaders/monitors like @babel/register, newrelic, sqreen, and ts-node.

• 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, and webpack.

  💡 By Node’s rules, builtin require cannot sideload .mjs files. However, with esm, ES modules can be sideloaded as .js files or .mjs files may be loaded with dynamic import.