# @std/esm
This fast, small, zero dependency, package is all you need to enable
ES modules in Node 4+ today!
:book: See the [release post](https://medium.com/web-on-the-edge/es-modules-in-node-today-32cff914e4b)
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**
```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.
```js
const loader1 = require("@std/esm")(module, { cjs: true, esm: "js" })
const loader2 = require("@std/esm")(module, true)
```
Enable ESM in the Node CLI by loading `@std/esm` with the [`-r` option](https://nodejs.org/api/cli.html#cli_r_require_module):
```shell
node -r @std/esm file.mjs
```
Enable ESM in the Node REPL by loading `@std/esm` upon entering:
```shell
$ 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](#unlockables) in the Node REPL.*
Standard Features
---
The `@std/esm` loader is as spec-compliant
as possible and follows [Node’s rules](https://github.com/nodejs/node-eps/blob/master/002-es-modules.md).
:point_right: This means, by default, ESM requires the use of the `.mjs` file
extension.
:unlock: You can [unlock](#unlockables) 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`](https://ponyfoo.com/articles/es6-modules-in-depth#import) / [`export`](https://ponyfoo.com/articles/es6-modules-in-depth#export)
* [Dynamic `import()`](https://github.com/tc39/proposal-dynamic-import)
* [Live bindings](https://ponyfoo.com/articles/es6-modules-in-depth#bindings-not-values)
* [Loading `.mjs` files as ESM](https://github.com/nodejs/node-eps/blob/master/002-es-modules.md#32-determining-if-source-is-an-es-module)
* [The file URI scheme](https://en.wikipedia.org/wiki/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" files with import, export, or "use module" as ESM