esm

What is esm?

The esm npm package is a lightweight module loader that allows developers to use ES6 modules in Node.js. It enables the use of import and export syntax for working with modules, which is more standardized and often considered cleaner than the traditional CommonJS require syntax.

What are esm's main functionalities?

Import ES6 Modules

Allows the use of ES6 import syntax in Node.js by requiring the esm module and then using it to load other ES6 modules.

require = require('esm')(module)
const { myFunction } = require('./myModule.mjs')

Export ES6 Modules

Enables developers to define modules using ES6 export syntax, which can then be imported by other modules.

// In myModule.mjs
export const myFunction = () => { console.log('Hello ESM!'); }

Dynamic Import

Supports dynamic import() syntax for loading modules asynchronously, which can be useful for code splitting or on-demand loading.

require = require('esm')(module)
const myModule = require('./myModule.mjs')
myModule.then(module => { module.myFunction() })

Other packages similar to esm

@babel/register

This package allows you to transpile your ES6+ code on the fly by hooking into Node's require. It is more feature-rich than esm, offering a wide range of plugins to transform your code, but it may be heavier and slower for simple use cases.

ts-node

While ts-node is primarily for running TypeScript in Node.js without pre-compiling, it also supports ES6+ features. It is similar to esm in that it allows for the use of modern module syntax, but it is specifically tailored for TypeScript.

esbuild-register

This package uses esbuild to transpile code when requiring modules. It's similar to esm in that it allows you to use newer syntax, but it also includes TypeScript support and is focused on speed, leveraging the fast esbuild bundler.

README

esm

A fast, production ready, zero-dependency ES module loader for Node 6+!

See the release post :book: and video :movie_camera: for all the details.

Install

• New projects

  Run npm init esm (with npm@6) 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 create-esm.

2. Enable esm for local runs:

   node -r esm main.js
   

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

Features

The esm loader bridges the ESM of today to the ESM of tomorrow.

:clap: By default, :100: percent CJS interoperability is enabled so you can get stuff done fast.
: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:

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

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

{
"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
"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. "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. }
"await":	A boolean for top-level await in modules without ESM exports.
}

DevOpts

{
"cache":	A boolean for toggling cache creation or string path of the cache directory.
"debug":	A boolean for unmasking stack traces.
"sourceMap":	A boolean for including inline source maps.
"warnings":	A boolean for logging development parse and runtime warnings.
}

Tips

• Load esm with the “require” option of
  ava, mocha, nodemon, nyc, qunit, tape, ts-node, and webpack
• Load esm before @babel/register
• Load esm with the --node-arg=-r --node-arg=esm option of node-tap
• Load esm with the --node-args="-r esm" option of pm2
• Load esm with wallaby.js
• Use esm to load jasmine