esm-sync 3.4.0 → 3.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +82 -243
- package/dist/esm/loader.js +14205 -51
- package/dist/esm.d.ts +11 -1
- package/dist/esm.js +2 -2
- package/dist/index.d.ts +11 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,263 +1,102 @@
|
|
|
1
1
|
# esm-sync
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A synchronous ECMAScript module loader for CommonJS, maintained as a fork of
|
|
4
|
+
[esm](https://github.com/standard-things/esm) for
|
|
5
|
+
[import-sync](https://github.com/nktnet1/import-sync).
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
The fork supports modern package `exports` and private `imports` maps,
|
|
8
|
+
`node:` specifiers, dynamic imports, live bindings, and `import.meta` helpers
|
|
9
|
+
(`url`, `resolve`, `dirname`, `filename`, and `main`). Modules may declare their
|
|
10
|
+
own `require`, including one created with `createRequire(import.meta.url)`.
|
|
6
11
|
|
|
7
|
-
|
|
8
|
-
* Support for modules that use the `const require = createRequire(...)` pattern (or declare any other global `require` variable) which are otherwise unusable with `esm`.
|
|
9
|
-
* Support for modules that use only an `exports` map in their package.json, without a `main` field, which are otherwise unresolvable (reporting "Cannot find module", even though `import()` works correctly).
|
|
10
|
-
* Built-in types for use in TypeScript projects
|
|
11
|
-
|
|
12
|
-
This package is maintained for use in the [import-sync](https://github.com/nktnet1/import-sync) project.
|
|
13
|
-
|
|
14
|
-
You may also be interested in [jiti](https://github.com/unjs/jiti), which provides legacy (deprecated, but still reliable) support for synchronous imports.
|
|
15
|
-
|
|
16
|
-
## Install
|
|
12
|
+
## Install and use
|
|
17
13
|
|
|
18
14
|
```sh
|
|
19
15
|
npm install esm-sync
|
|
20
16
|
```
|
|
21
17
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
There are two ways to enable `esm-sync`.
|
|
25
|
-
|
|
26
|
-
1. Enable `esm-sync` for packages:
|
|
27
|
-
|
|
28
|
-
Use `esm-sync` to load the main ES module and export it as CommonJS.
|
|
29
|
-
|
|
30
|
-
__index.js__
|
|
31
|
-
```js
|
|
32
|
-
// Set options as a parameter, environment variable, or rc file.
|
|
33
|
-
require = require("esm-sync")(module/*, options*/)
|
|
34
|
-
module.exports = require("./main.js")
|
|
35
|
-
```
|
|
36
|
-
__main.js__
|
|
37
|
-
```js
|
|
38
|
-
// ESM syntax is supported.
|
|
39
|
-
export {}
|
|
40
|
-
```
|
|
18
|
+
In a CommonJS entry point:
|
|
41
19
|
|
|
42
|
-
|
|
20
|
+
```js
|
|
21
|
+
const load = require("esm-sync")(module)
|
|
22
|
+
module.exports = load("./main.js")
|
|
23
|
+
```
|
|
43
24
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
25
|
+
```js
|
|
26
|
+
// main.js
|
|
27
|
+
export const answer = 42
|
|
28
|
+
```
|
|
48
29
|
|
|
49
|
-
|
|
30
|
+
To enable Node's preload hooks for a script or REPL:
|
|
50
31
|
|
|
51
|
-
|
|
52
|
-
|
|
32
|
+
```sh
|
|
33
|
+
node --require esm-sync main.js
|
|
34
|
+
node --require esm-sync
|
|
35
|
+
```
|
|
53
36
|
|
|
54
|
-
|
|
37
|
+
Calling `require("esm-sync")` alone returns the factory; use its returned
|
|
38
|
+
require function to load modules. Built-in TypeScript declarations cover the
|
|
39
|
+
factory and its options.
|
|
55
40
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
* Node [`--check`](https://nodejs.org/api/cli.html#cli_c_check) flag _(Node 10+)_
|
|
41
|
+
Top-level `await`, asynchronous module dependencies, and module-body resource
|
|
42
|
+
disposal are supported. Synchronous timer/I/O awaits require a compatible native
|
|
43
|
+
bridge and the initial CommonJS startup stack. The bridge targets Node 22+;
|
|
44
|
+
ordinary loading retains the declared Node `>=6` range, with syntax support
|
|
45
|
+
limited by the host. Current CI tests Node 22, 24, and 26 on Linux, macOS, and
|
|
46
|
+
Windows. See [async module loading](docs/async-module-loading.md) for installation,
|
|
47
|
+
context restrictions, errors, and timeouts.
|
|
64
48
|
|
|
65
49
|
## Options
|
|
66
50
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
<p>A boolean for <code>__esModule</code> interoperability.</p>
|
|
99
|
-
</td>
|
|
100
|
-
</tr>
|
|
101
|
-
<tr>
|
|
102
|
-
<td valign="top"><code>"extensions":true</code></td>
|
|
103
|
-
<td>
|
|
104
|
-
<p>A boolean for respecting <code>require.extensions</code> in ESM.</p>
|
|
105
|
-
</td>
|
|
106
|
-
</tr>
|
|
107
|
-
<tr>
|
|
108
|
-
<td valign="top"><code>"mutableNamespace":true</code></td>
|
|
109
|
-
<td>
|
|
110
|
-
<p>A boolean for mutable <a href="https://ponyfoo.com/articles/es6-modules-in-depth#import-all-the-things">namespace objects</a>.</p>
|
|
111
|
-
</td>
|
|
112
|
-
</tr>
|
|
113
|
-
<tr>
|
|
114
|
-
<td valign="top"><code>"namedExports":true</code></td>
|
|
115
|
-
<td>
|
|
116
|
-
<p>A boolean for <a href="https://ponyfoo.com/articles/es6-modules-in-depth#importing-named-exports">importing named exports</a> of CJS modules.</p>
|
|
117
|
-
</td>
|
|
118
|
-
</tr>
|
|
119
|
-
<tr>
|
|
120
|
-
<td valign="top"><code>"paths":true</code></td>
|
|
121
|
-
<td>
|
|
122
|
-
<p>A boolean for following CJS <a href="https://github.com/nodejs/node-eps/blob/master/002-es-modules.md#432-removal-of-non-local-dependencies">path rules</a> in ESM.</p>
|
|
123
|
-
</td>
|
|
124
|
-
</tr>
|
|
125
|
-
<tr>
|
|
126
|
-
<td valign="top"><code>"vars":true</code></td>
|
|
127
|
-
<td>
|
|
128
|
-
<p>A boolean for <code>__dirname</code>, <code>__filename</code>, and <code>require</code> in ESM.</p>
|
|
129
|
-
</td>
|
|
130
|
-
</tr>
|
|
131
|
-
<tr>
|
|
132
|
-
<td valign="top"><code>"dedefault":false</code></td>
|
|
133
|
-
<td>
|
|
134
|
-
<p>A boolean for requiring ES modules without the dangling <code>require().default</code>.</p>
|
|
135
|
-
</td>
|
|
136
|
-
</tr>
|
|
137
|
-
<tr>
|
|
138
|
-
<td valign="top"><code>"topLevelReturn":false</code></td>
|
|
139
|
-
<td>
|
|
140
|
-
<p>A boolean for top-level <code>return</code> support.</p>
|
|
141
|
-
</td>
|
|
142
|
-
</tr>
|
|
143
|
-
<tr>
|
|
144
|
-
<td colspan="2"><code>}</code></td>
|
|
145
|
-
</tr>
|
|
146
|
-
</table>
|
|
147
|
-
</details>
|
|
148
|
-
</td>
|
|
149
|
-
</tr>
|
|
150
|
-
<tr>
|
|
151
|
-
<td valign="top"><code>"mainFields":["main"]</code></td>
|
|
152
|
-
<td>
|
|
153
|
-
<p>An array of fields checked when importing a package.</p>
|
|
154
|
-
</td>
|
|
155
|
-
</tr>
|
|
156
|
-
<tr>
|
|
157
|
-
<td valign="top"><code>"mode":"auto"</code></td>
|
|
158
|
-
<td>
|
|
159
|
-
<p>A string mode:</p>
|
|
160
|
-
<ul>
|
|
161
|
-
<li><code>"auto"</code> detect files with <code>import</code>, <code>import.meta</code>, <code>export</code>,<br><a href="https://github.com/tc39/proposal-modules-pragma"><code>"use module"</code></a>, or <code>.mjs</code> as ESM.</li>
|
|
162
|
-
<li><code>"all"</code> files besides those with <code>"use script"</code> or <code>.cjs</code> are treated as ESM.</li>
|
|
163
|
-
<li><code>"strict"</code> to treat <strong>only</strong> <code>.mjs</code> files as ESM.</li>
|
|
164
|
-
</ul>
|
|
165
|
-
</td>
|
|
166
|
-
</tr>
|
|
167
|
-
<tr>
|
|
168
|
-
<td valign="top"><code>"await":false</code></td>
|
|
169
|
-
<td>
|
|
170
|
-
<p>A boolean for <a href="https://github.com/tc39/proposal-top-level-await">top-level <code>await</code></a> in modules without ESM exports. <em>(Node 10+)</em></p>
|
|
171
|
-
</td>
|
|
172
|
-
</tr>
|
|
173
|
-
<tr>
|
|
174
|
-
<td valign="top"><code>"force":false</code></td>
|
|
175
|
-
<td>
|
|
176
|
-
<p>A boolean to apply these options to all module loads.</p>
|
|
177
|
-
</td>
|
|
178
|
-
</tr>
|
|
179
|
-
<tr>
|
|
180
|
-
<td valign="top"><code>"wasm":false</code></td>
|
|
181
|
-
<td>
|
|
182
|
-
<p>A boolean for <a href="https://nodejs.org/api/globals.html#globals_webassembly">WebAssembly</a> module support. <em>(Node 8+)</em></p>
|
|
183
|
-
</td>
|
|
184
|
-
</tr>
|
|
185
|
-
<tr>
|
|
186
|
-
<td colspan="2"><code>}</code></td>
|
|
187
|
-
</tr>
|
|
188
|
-
</table>
|
|
189
|
-
|
|
190
|
-
DevOpts
|
|
191
|
-
---
|
|
51
|
+
Pass options to `require("esm-sync")(module, options)`, or configure them with
|
|
52
|
+
an `"esm"` package field, `.esmrc[.json]` (JSON6), `.esmrc.js`/`.cjs`/`.mjs`, or
|
|
53
|
+
`ESM_OPTIONS` (JSON6 or a configuration-file path).
|
|
54
|
+
|
|
55
|
+
| Option | Default | Purpose |
|
|
56
|
+
| ------------ | ---------- | --------------------------------------------------------------------------------------------------------------- |
|
|
57
|
+
| `mode` | `"auto"` | Detect module syntax; `"all"` treats files as ESM except `.cjs`/`"use script"`; `"strict"` selects `.mjs` only. |
|
|
58
|
+
| `cjs` | `true` | Enable CommonJS conveniences in eligible `.js` modules, or configure individual features below. |
|
|
59
|
+
| `mainFields` | `["main"]` | Legacy package entry fields; a package `exports` map takes precedence. |
|
|
60
|
+
| `cache` | `true` | Enable persistent compilation caching; use a string for its directory or `false` to disable it. |
|
|
61
|
+
| `sourceMap` | automatic | Include inline source maps when enabled. |
|
|
62
|
+
| `await` | `false` | Also permit top-level await in modules without ESM exports. |
|
|
63
|
+
| `force` | `false` | Apply this configuration across package boundaries. |
|
|
64
|
+
| `wasm` | `false` | Enable WebAssembly module loading on capable hosts. |
|
|
65
|
+
| `debug` | `false` | Expose loader internals in diagnostic stacks. |
|
|
66
|
+
|
|
67
|
+
`cjs` accepts booleans for `cache`, `esModule`, `extensions`,
|
|
68
|
+
`mutableNamespace`, `namedExports`, `paths`, and `vars`. These default to `true`
|
|
69
|
+
in zero-configuration `.js` interop. `dedefault` and `topLevelReturn` default
|
|
70
|
+
to `false`. Strict `.mjs` graphs retain their ESM boundaries. See
|
|
71
|
+
[interop and migration](docs/interop-and-migration.md) for default-export
|
|
72
|
+
unwrapping, Mocha setup, package resolution, mocking, and native Node migration.
|
|
73
|
+
|
|
74
|
+
Set `ESM_DISABLE_CACHE=true` or `1` before loading to bypass persistent compiler
|
|
75
|
+
and bootstrap caches. This does not re-evaluate modules already in memory.
|
|
76
|
+
|
|
77
|
+
## Development
|
|
78
|
+
|
|
79
|
+
On macOS or Linux with Node.js 22.18+ (using your current Node version), pnpm,
|
|
80
|
+
and development dependencies installed, run
|
|
81
|
+
full local release verification:
|
|
192
82
|
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
</tr>
|
|
197
|
-
<tr>
|
|
198
|
-
<td valign="top"><code>"cache":true</code></td>
|
|
199
|
-
<td>
|
|
200
|
-
<p>A boolean for toggling cache creation or a cache directory path.</p>
|
|
201
|
-
</td>
|
|
202
|
-
</tr>
|
|
203
|
-
<tr>
|
|
204
|
-
<td valign="top"><code>"sourceMap":false</code></td>
|
|
205
|
-
<td>
|
|
206
|
-
<p>A boolean for including inline source maps.</p>
|
|
207
|
-
</td>
|
|
208
|
-
</tr>
|
|
209
|
-
<tr>
|
|
210
|
-
<td colspan="2"><code>}</code></td>
|
|
211
|
-
</tr>
|
|
212
|
-
</table>
|
|
213
|
-
|
|
214
|
-
Tips
|
|
215
|
-
---
|
|
216
|
-
|
|
217
|
-
### Bundling
|
|
218
|
-
|
|
219
|
-
* For bundlers like [`browserify`](http://browserify.org/)+[`esmify`](https://github.com/mattdesl/esmify),
|
|
220
|
-
[`parcel-bundler`](https://parceljs.org/), and [`webpack`](https://webpack.js.org/)
|
|
221
|
-
add a `"module"` field to `package.json` pointing to the main ES module.
|
|
222
|
-
```json
|
|
223
|
-
"main": "index.js",
|
|
224
|
-
"module": "main.js"
|
|
225
|
-
```
|
|
226
|
-
|
|
227
|
-
:bulb: This is automagically done with `npm init esm` or `yarn create esm`.
|
|
228
|
-
|
|
229
|
-
### Extensions
|
|
230
|
-
|
|
231
|
-
* Enable `esm-sync` for [`wallaby.js`](https://wallabyjs.com/) following their
|
|
232
|
-
[integration example](https://wallabyjs.com/docs/integration/node.html#es-modules).
|
|
233
|
-
|
|
234
|
-
### Loading
|
|
235
|
-
|
|
236
|
-
* Load `esm-sync` before loaders/monitors like
|
|
237
|
-
[`@babel/register`](https://babeljs.io/docs/en/next/babel-register.html),
|
|
238
|
-
[`newrelic`](https://github.com/newrelic/node-newrelic),
|
|
239
|
-
[`ts-node`](https://github.com/TypeStrong/ts-node#programmatic).
|
|
240
|
-
|
|
241
|
-
* Load `esm-sync` for [`jasmine`](https://jasmine.github.io/) using the
|
|
242
|
-
[`"helpers"`](https://jasmine.github.io/setup/nodejs.html#configuration)
|
|
243
|
-
field in `jasmine.json`:
|
|
244
|
-
```json
|
|
245
|
-
"helpers": [
|
|
246
|
-
"node_modules/esm-sync"
|
|
247
|
-
]
|
|
248
|
-
```
|
|
249
|
-
|
|
250
|
-
* Load `esm-sync` with “node-args" options of:<br>
|
|
251
|
-
- [`pm2`](https://pm2.io/doc/en/runtime/reference/pm2-cli/#pm2-flags): `--node-args="-r esm-sync"`
|
|
252
|
-
|
|
253
|
-
* Load `esm-sync` with “require” options of
|
|
254
|
-
[`ava`](https://github.com/avajs/ava/blob/master/docs/recipes/es-modules.md),
|
|
255
|
-
[`mocha`](https://mochajs.org/#-require-module-r-module),
|
|
256
|
-
[`nodemon`](https://nodemon.io/),
|
|
257
|
-
[`nyc`](https://github.com/istanbuljs/nyc#require-additional-modules),
|
|
258
|
-
[`qunit`](https://github.com/qunitjs/qunit/releases/tag/2.6.0),
|
|
259
|
-
[`tape`](https://github.com/substack/tape#preloading-modules), and
|
|
260
|
-
[`webpack`](https://webpack.js.org/api/cli/#config-options).
|
|
83
|
+
```sh
|
|
84
|
+
pnpm verify:all
|
|
85
|
+
```
|
|
261
86
|
|
|
262
|
-
|
|
263
|
-
|
|
87
|
+
This orchestrates the existing `package.json` scripts **natively** for the
|
|
88
|
+
fixture setup, the production test build and complete Vitest suite (`verify:prod`), one production
|
|
89
|
+
Test262 run, the publishable build and installed-package tests, benchmarks,
|
|
90
|
+
lint, typechecking, Knip, a dependency audit, and a disposable Verdaccio registry.
|
|
91
|
+
Only the Electron/VS Code/USB/WebContainer host checks use Docker. The command
|
|
92
|
+
requires network access for fixture and host dependencies. CI tests other Node
|
|
93
|
+
versions and operating systems. A failed or blocked stage fails verification;
|
|
94
|
+
logs and summaries are saved under `dist/verification/`. Nothing publishes to npm.
|
|
95
|
+
|
|
96
|
+
- [Maintainer guide and focused commands](docs/MAINTAINER_GUIDE.md)
|
|
97
|
+
- [CI selection and caches](docs/ci.md)
|
|
98
|
+
- [Host integration scope](docs/host-integrations.md)
|
|
99
|
+
- [Original application and performance checks](docs/tooling-and-performance.md)
|
|
100
|
+
- [Compatibility scope and remaining work](docs/FORK_ISSUES_ROADMAP.md)
|
|
101
|
+
- [v3.4.0 release notes](docs/releases/v3.4.0.md)
|
|
102
|
+
- [Release procedure](script/RELEASING.md)
|