Tomorrow's ECMAScript modules today!
npm install @httptoolkit/esm> _Part of HTTP Toolkit: powerful tools for building, testing & debugging HTTP(S)_
This is a forked version of the esm package: the brilliantly simple, babel-less, bundle-less ECMAScript module loader (which is now unmaintained). This fork includes:
Assorted updates from the esm-wallaby fork adding support for ES modules containing new ES syntax, supporting modern Node versions (at least up to v21), and supporting node: imports.
* Support for modules that use the const require = createRequire(...) pattern (or declare any other global require variable) which are otherwise unusable with esm.
* Support for modules that use only an exports map in their package.json, without a main field, which are otherwise unresolveable (reporting "Cannot find module", even though import() works correctly).
Install
---
Run npm i @httptoolkit/esm or yarn add @httptoolkit/esm.
Getting started
---
There are two ways to enable @httptoolkit/esm.
1. Enable @httptoolkit/esm for packages:
Use @httptoolkit/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("@httptoolkit/esm")(module/, options/)
module.exports = require("./main.js")
`
__main.js__
js`
// ESM syntax is supported.
export {}
2. Enable @httptoolkit/esm for local runs:
`shell`
node -r @httptoolkit/esm main.js
@httptoolkit/esm
:bulb: Omit the filename to enable 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 @httptoolkit/esm options.
Out of the box @httptoolkit/esm just works, no configuration necessary, and supports:
* Passing all applicable test262 compliance tests
* import/export
* import.meta
* Dynamic import
* Live bindings
* File URI scheme
* Node stdin, --eval, --print flags--check
* Node flag _(Node 10+)_
Options
---
Specify options with one of the following:
* "esm" field in package.json.esmrc.js
* CJS/ESM in an , .esmrc.cjs, or .esmrc.mjs file.esmrc
* JSON6 in an or .esmrc.json fileESM_OPTIONS
* JSON6 or file path in the environment variableESM_DISABLE_CACHE
* environment variable
{ | |||||||||||||||||||||||
"cjs":true | A boolean or object for toggling CJS features in ESM. A boolean for storing ES modules in A boolean for A boolean for respecting A boolean for mutable namespace objects. A boolean for importing named exports of CJS modules. A boolean for following CJS path rules in ESM. A boolean for A boolean for requiring ES modules without the dangling A boolean for top-level | ||||||||||||||||||||||
"mainFields":["main"] | An array of fields checked when importing a package. | ||||||||||||||||||||||
"mode":"auto" | A string mode:
| ||||||||||||||||||||||
"await":false | A boolean for top-level | ||||||||||||||||||||||
"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
---
* For bundlers like browserify+esmify,
parcel-bundler, and webpack
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.
* Enable @httptoolkit/esm for wallaby.js following their
integration example.
* Load @httptoolkit/esm before loaders/monitors like@babel/register
,newrelic
,sqreen
, andts-node
.
* Load @httptoolkit/esm for jasmine using the"helpers"
jasmine.json
field in :`
json`
"helpers": [
"node_modules/@httptoolkit/esm"
]
* Load @httptoolkit/esm with “node-args" options of:pm2
- : --node-args="-r @httptoolkit/esm"
* Load @httptoolkit/esm with “require” options ofava
,mocha
,nodemon
,nyc
,qunit
,tape
, andwebpack
.
:bulb: Builtin require cannot sideload .mjs files. However, .js files.mjs
can be sideloaded or files may be loaded with dynamic import`.