esm

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

esmis 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 releasepost andvideofor details!

Install

• New projects

  Runnpm init esmoryarn create esm.

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

• Existing projects

  Runnpm i esmoryarn add esm.

Getting started

There are two ways to enableesm.

1. Enableesmfor packages:

   Useesmto 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 withnpm init esmoryarn create esm.

2. Enableesmfor local runs:

   node -r esm main.js

   💡 Omit the filename to enableesmin the REPL.

Features

👏 By default, 💯 percent CJS interoperability is enabled so you can get stuff done.
🔒.mjsfiles are limited to basic functionality without support foresmoptions.

Out of the boxesmjust works, no configuration necessary, and supports:

• Passing all applicabletest262compliance tests
• import/export
• import.meta
• Dynamicimport
• Live bindings
• File URI scheme
• Nodestdin,--eval,--printflags
• Node--checkflag(Node 10+)

Options

Specify options with one of the following:

• "esm"field inpackage.json
• CJS/ESM in an.esmrc.js,.esmrc.cjs,or.esmrc.mjsfile
• JSON6in an.esmrcor.esmrc.jsonfile
• JSON6 or file path in theESM_OPTIONSenvironment variable
• ESM_DISABLE_CACHEenvironment variable

{
"cjs":true	A boolean or object for toggling CJS features in ESM. Features { "cache":true A boolean for storing ES modules inrequire.cache. "esModule":true A boolean for__esModuleinteroperability. "extensions":true A boolean for respectingrequire.extensionsin ESM. "mutableNamespace":true A boolean for mutablenamespace objects. "namedExports":true A boolean forimporting named exportsof CJS modules. "paths":true A boolean for following CJSpath rulesin ESM. "vars":true A boolean for__dirname,__filename,andrequirein ESM. "dedefault":false A boolean for requiring ES modules without the danglingrequire().default. "topLevelReturn":false A boolean for top-levelreturnsupport. }
"mainFields":[ "main" ]	An array of fields checked when importing a package.
"mode": "auto"	A string mode: "auto"detect files withimport,import.meta,export, "use module",or.mjsas ESM. "all"files besides those with"use script"or.cjsare treated as ESM. "strict"to treatonly.mjsfiles as ESM.
"await":false	A boolean fortop-levelawaitin modules without ESM exports.(Node 10+)
"force":false	A boolean to apply these options to all module loads.
"wasm":false	A boolean forWebAssemblymodule 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 likebrowserify+esmify, parcel-bundler,andwebpack add a"module"field topackage.jsonpointing to the main ES module.

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

  💡 This is automagically done withnpm init esmoryarn create esm.

Extensions

• Enableesmforwallaby.jsfollowing their integration example.

Loading

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

• Loadesmforjasmineusing the "helpers" field injasmine.json:

  "helpers":[
  "node_modules/esm"
  ]

• Loadesmwith “node-args" options of:
  

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

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

  💡 Builtinrequirecannot sideload.mjsfiles. However,.jsfiles can be sideloaded or.mjsfiles may be loaded with dynamicimport.