esm

Tomorrow's ECMAScript modules today!

standard-things/esmesm

README

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__
  1. ``` js
  2.     // Set options as a parameter, environment variable, or rc file.
  3.     require = require("esm")(module/*, options*/)
  4.     module.exports = require("./main.js")
  5. ```
    __main.js__
  1. ``` js
  2.     // ESM syntax is supported.
  3.     export {}
  4. ```
    :bulb: These files are automagically created with npm init esm or yarn create esm.

2. Enable esm for local runs:

  1. ``` sh
  2.     node -r esm main.js
  3. ```
    :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](https://ponyfoo.com/articles/es6-modules-in-depth#import)/[export](https://ponyfoo.com/articles/es6-modules-in-depth#export)
[import.meta](https://github.com/tc39/proposal-import-meta)
[Dynamic import](https://github.com/tc39/proposal-dynamic-import)
Live bindings
File URI scheme
Node stdin, [--eval](https://nodejs.org/api/cli.html#cli_e_eval_script), [--print](https://nodejs.org/api/cli.html#cli_p_print_script) flags
Node [--check](https://nodejs.org/api/cli.html#cli_c_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

{
"cjs":true

A boolean or object for toggling CJS features in ESM.

Features
{
"cache":true

A boolean for storing ES modules in require.cache.
"esModule":true

A boolean for __esModule interoperability.
"extensions":true

A boolean for respecting require.extensions in ESM.
"mutableNamespace":true

A boolean for mutable namespace objects.
"namedExports":true

A boolean for importing named exports of CJS modules.
"paths":true

A boolean for following CJS path rules in ESM.
"vars":true

A boolean for __dirname, __filename, and require in ESM.
"dedefault":false

A boolean for requiring ES modules without the dangling require().default.
"topLevelReturn":false

A boolean for top-level return support.
}
"mainFields":["main"]

An array of fields checked when importing a package.

"mode":"auto"

A string mode:

  • "auto" detect files with import, import.meta, export,
    "use module", or .mjs as ESM.
  • "all" files besides those with "use script" or .cjs are treated as ESM.
  • "strict" to treat only .mjs files as ESM.
"await":false

A boolean for top-level await in modules without ESM exports. (Node 10+)

"force":false

A boolean to apply these options to all module loads.

"wasm":false

A boolean for WebAssembly module support. (Node 8+)

}

DevOpts

{
"cache":true

A boolean for toggling cache creation or a cache directory path.

"sourceMap":false

A boolean for including inline source maps.

}

Tips

Bundling


For bundlers like [browserify](http://browserify.org/)+[esmify](https://github.com/mattdesl/esmify),
  [parcel-bundler](https://parceljs.org/), and [webpack](https://webpack.js.org/)
  add a "module" field to package.json pointing to the main ES module.
  1. ``` json
  2.   "main": "index.js",
  3.   "module": "main.js"
  4. ```

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

Extensions


Enable esm for [wallaby.js](https://wallabyjs.com/) following their
  integration example.

Loading


Load esm before loaders/monitors like
  [@babel/register](https://babeljs.io/docs/en/next/babel-register.html),
  [newrelic](https://github.com/newrelic/node-newrelic),
  [sqreen](https://docs.sqreen.io/sqreen-for-nodejs/getting-started-2/), and
  [ts-node](https://github.com/TypeStrong/ts-node#programmatic).

Load esm for [jasmine](https://jasmine.github.io/) using the
  ["helpers"](https://jasmine.github.io/setup/nodejs.html#configuration)
  field in jasmine.json:
  1. ``` json
  2.   "helpers": [
  3.     "node_modules/esm"
  4.   ]
  5. ```

* Load `esm` with “node-args" options of:
  - [pm2](https://pm2.io/doc/en/runtime/reference/pm2-cli/#pm2-flags): --node-args="-r esm"

Load esm with “require” options of
  [ava](https://github.com/avajs/ava/blob/master/docs/recipes/es-modules.md),
  [mocha](https://mochajs.org/#-require-module-r-module),
  [nodemon](https://nodemon.io/),
  [nyc](https://github.com/istanbuljs/nyc#require-additional-modules),
  [qunit](https://github.com/qunitjs/qunit/releases/tag/2.6.0),
  [tape](https://github.com/substack/tape#preloading-modules), and
  [webpack](https://webpack.js.org/api/cli/#config-options).

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