Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/standard-things/esm

Tomorrow's ECMAScript modules today!
https://github.com/standard-things/esm

es6 es6-modules esm esmodules nodejs

Last synced: 3 days ago
JSON representation

Tomorrow's ECMAScript modules today!

Awesome Lists containing this project

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](https://medium.com/web-on-the-edge/tomorrows-es-modules-today-c53d29ac448c)

and [video](https://www.youtube.com/watch?v=JcZ-FzfDq8A#t=5) 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__

    ```js

    // Set options as a parameter, environment variable, or rc file.

    require = require("esm")(module/*, options*/)

    module.exports = require("./main.js")

    ```

    __main.js__

    ```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:



    ```shell

    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](https://github.com/tc39/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](https://ponyfoo.com/articles/es6-modules-in-depth#bindings-not-values)

* [File URI scheme](https://en.wikipedia.org/wiki/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](https://github.com/d3x0r/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.

  ```json

  "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`](https://wallabyjs.com/) following their

  [integration example](https://wallabyjs.com/docs/integration/node.html#es-modules).



### 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`:

  ```json

  "helpers": [

    "node_modules/esm"

  ]

  ```



* 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`.