Commit 56b150b
doc: add current recommendation for ESM/CommonJS dual packages
PR-URL: #27957
Reviewed-By: Ujjwal Sharma <usharma1998@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Jan Krems <jan.krems@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>1 parent 360c708 commit 56b150b
1 file changed
Lines changed: 9 additions & 10 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -206,16 +206,15 @@ a full path including extension: `"./index.mjs"`, not `"./index"`. | |||
| 206 | 206 | If the `package.json` `"type"` field is omitted, a `.js` file in `"main"` will | |
| 207 | 207 | be interpreted as CommonJS. | |
| 208 | 208 | ||
| 209 | - > Currently a package can define _either_ a CommonJS entry point **or** an ES | ||
| 210 | - > module entry point; there is no way to specify separate entry points for | ||
| 211 | - > CommonJS and ES module usage. This means that a package entry point can be | ||
| 212 | - > included via `require` or via `import` but not both. | ||
| 213 | - > | ||
| 214 | - > Such a limitation makes it difficult for packages to support both new versions | ||
| 215 | - > of Node.js that understand ES modules and older versions of Node.js that | ||
| 216 | - > understand only CommonJS. There is work ongoing to remove this limitation, and | ||
| 217 | - > it will very likely entail changes to the behavior of `"main"` as defined | ||
| 218 | - > here. | ||
| 209 | + The `"main"` field can point to exactly one file, regardless of whether the | ||
| 210 | + package is referenced via `require` (in a CommonJS context) or `import` (in an | ||
| 211 | + ES module context). Package authors who want to publish a package to be used in | ||
| 212 | + both contexts can do so by setting `"main"` to point to the CommonJS entry point | ||
| 213 | + and informing the package’s users of the path to the ES module entry point. Such | ||
| 214 | + a package would be accessible like `require('pkg')` and `import | ||
| 215 | + 'pkg/module.mjs'`. Alternatively the package `"main"` could point to the ES | ||
| 216 | + module entry point and legacy users could be informed of the CommonJS entry | ||
| 217 | + point path, e.g. `require('pkg/commonjs')`. | ||
| 219 | 218 | ||
| 220 | 219 | ## <code>import</code> Specifiers | |
| 221 | 220 | ||
0 commit comments