esm

The brilliantly simple, babel-less, bundle-less ECMAScript module loader.

esm is the world’s most advanced ECMAScript module loader.
This fast, production ready, zero dependency loader is all you need to support
ECMAScript modules in Node 6+. See the release post
and video for details!

Install

• New projects

  Run npm init esm or yarn create esm.

  :bulb: 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 {}
   

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

2. Enable esm for local runs:

   node -r esm main.js
   

   :bulb: Omit the filename to enable esm in the REPL.

Features

:clap: By default, :100: percent CJS interoperability is enabled so you can get stuff done.
:lock: .mjs files are limited to basic functionality without support for esm options.

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

• Passing all applicable test262 compliance tests
• import/export
• import.meta
• Dynamic import
• Live bindings
• File URI scheme
• Node stdin, --eval, --print flags
• Node --check flag (Node 10+)

Options

Specify options with one of the following:

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

DevOpts

Tips

Bundling

• For bundlers like browserify+esmify,
  parcel-bundler, and webpack
  add a "module" field to package.json pointing to the main ES module.

  "main": "index.js",
  "module": "main.js"
  

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

Extensions

• Enable esm for wallaby.js following their
  integration example.

Loading

• Load esm before loaders/monitors like
  @babel/register,
  newrelic,
  sqreen, and
  ts-node.

• Load esm for jasmine using the
  "helpers"
  field in jasmine.json:

  "helpers": [
    "node_modules/esm"
  ]
  

• Load esm with “node-args" options of:

  • pm2: --node-args="-r esm"

• Load esm with “require” options of
  ava,
  mocha,
  nodemon,
  nyc,
  qunit,
  tape, and
  webpack.

  :bulb: Builtin require cannot sideload .mjs files. However, .js files
  can be sideloaded or .mjs files may be loaded with dynamic import.