Norvell's Public Machinations

    esm
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/esm package

    3.2.25 • Public • Published

    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.

      💡 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

    👏 By default, 💯 percent CJS interoperability is enabled so you can get stuff done.
    🔒 .mjs files are limited to basic functionality without support for esm options.

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

    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+esmify, parcel-bundler, and webpack add a "module" field to package.json pointing to the main ES module.

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

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

    Extensions

    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.

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

    Install

    npm i esm

    DownloadsWeekly Downloads

    2,018,812

    Version

    3.2.25

    License

    MIT

    Unpacked Size

    309 kB

    Total Files

    6

    Last publish

    Collaborators

    • jdalton