lukejagodzinski/esm

ES modules in Node today!

@std/esm

This fast, small, zero-dependency package is all you need to enable ES modules in Node 4+ today!

📖 See the release post for all the details.

Getting started

1. Run npm i --save @std/esm in your app or package directory.

2. Add .esm-cache to your .gitignore.

3. Create the ESM loader to import your main ES module:

   index.js

   require = require("@std/esm")(module)
   module.exports = require("./main.mjs").default

   By default, @std/esm only processes files of packages that opt-in with a @std/esm options object or @std/esm as a dependency, dev dependency, or peer dependency in their package.json. However, you can enable processing all files with specific options by passing an options object as the second argument or passing true to use the options from your package.json.

   require = require("@std/esm")(module, optionsOrTrue)

Enable ESM in the Node CLI by loading @std/esm with the -r option:

node -r @std/esm file.mjs

Enable ESM in the Node REPL by loading @std/esm 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.

Standard Features

The @std/esm loader is as spec-compliant as possible and follows Node’s 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

Unlockables

Unlock extra features with "@std/esm":options or "@std":{"esm":options} in your package.json.

Note: All options are off by default and may be specified as either an object or ESM mode string.

{ "@std/esm": {
"esm":	A string ESM mode: "mjs" files as ESM (default) "all" files as ESM "js" and other files with import, export, or "use module" as ESM
"cjs":	A boolean for CJS features in ESM: __dirname and __filename require in ESM and loading ESM with require Importing named exports of CJS modules Top-level return
"await":	A boolean for top-level await in the main ES module.
"gz":	A boolean for gzipped module support (i.e. .js.gz, .mjs.gz). Note: Don’t forget the webpack gzip-loader.
} }

DevOpts

{ "@std/esm": {
"debug":	A boolean for unmasking stack traces.
"sourceMap":	A boolean for enabling inline source maps. Note: Automatically enabled using the Node CLI --inspect option.
"warnings":	A boolean for enabling parse and runtime warnings. Note: The default value is process.env.NODE_ENV !== "production".
} }