This fast, small, zero-dependency package is all you need to enable ES modules in Node 4+ today!
See the release post 📖 and video 🎥 for all the details.
-
Run
npm i --save @std/esm
in your app or package directory. -
Create the ESM loader to import your main ES module:
index.js
require = require("@std/esm")(module) module.exports = require("./main.mjs").default
Enable processing all modules, including dependencies, by providing an
options
object or true
to use the options from your .esmrc or package.json.
require = require("@std/esm")(module, options)
Enable ESM in the Node CLI with the -r
option:
node -r @std/esm file.mjs
Enable ESM in the Node REPL:
node -r @std/esm
Or upon entering:
$ node
> require("@std/esm")
@std/esm enabled
> import p from "path"
undefined
> p.join("hello", "world")
'hello/world'
Note: The "cjs"
and "gz"
options are unlocked in the Node REPL.
The @std/esm
loader is as spec-compliant
as possible and follows Node’s ESM rules.
👉 This means, by default, ESM requires the use of the .mjs
file
extension.
🔓 You can unlock ESM with the .js
file extension using
the "js"
ESM mode.
Out of the box @std/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 4+ support
Unlock extra features by specifying options in your .esmrc or "@std/esm"
field
of your package.json.
Commonly used options may be specified in shorthand form:
"@std/esm":"js"
is shorthand for"@std/esm":{"esm":"js"}
"@std/esm":"cjs"
is shorthand for"@std/esm":{"cjs":true,"esm":"js"}
|
|
"esm": |
A string ESM mode:
|
"cjs": |
A boolean to unlock CJS features in ESM. |
"await": |
A boolean to support top-level |
"gz": |
A boolean to support gzipped module (i.e. Note: Don’t forget the webpack |
|
The "cjs"
option may also be specified as an object.
|
|
"cache": |
A boolean for storing ES modules in |
"extensions": |
A boolean for respecting |
"interop": |
A boolean for |
"namedExports": |
A boolean to support importing named exports of CJS modules. |
"paths": |
A boolean for following CJS path rules in ESM. |
"topLevelReturn": |
A boolean to support top-level |
"vars": |
A boolean to expose |
|
|
|
"cache": |
A boolean for toggling |
"debug": |
A boolean for unmasking stack traces. |
"sourceMap": |
A boolean for including inline source maps. Note: Automatically enabled using the Node CLI
|
"warnings": |
A boolean for logging parse and runtime warnings. (default: |
|
- Load
@std/esm
before@babel/register
v7+ - Load
@std/esm
with the “require” option ofava
,mocha
,nyc
, andtape
- Load
@std/esm
with the--node-arg=-r --node-arg=@std/esm
option ofnode-tap
- Load
@std/esm
with the--node-args="-r @std/esm"
option ofpm2
- Use
"@std/esm":"cjs"
with the--watch
and--watch-extensions
options ofmocha
- Use
"@std/esm":"cjs"
withwebpack
- When in doubt, use
"@std/esm":"cjs"