Skip to content
This repository was archived by the owner on Apr 16, 2020. It is now read-only.

Commit 62c73b2

Browse files
committed
doc: add current recommendation for ESM/CommonJS dual packages
1 parent 0ca9297 commit 62c73b2

File tree

1 file changed

+9
-10
lines changed

1 file changed

+9
-10
lines changed

doc/api/esm.md

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -206,16 +206,15 @@ a full path including extension: `"./index.mjs"`, not `"./index"`.
206206
If the `package.json` `"type"` field is omitted, a `.js` file in `"main"` will
207207
be interpreted as CommonJS.
208208

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` or `import`. Package authors who want to
211+
publish a package to be used both by older versions of Node.js (via `require`)
212+
and Node.js 12+ (via `import`) can do so by setting `"main"` to point to the
213+
CommonJS entry point and informing the package’s users of the path to the ES
214+
module entry point. Such a package would be accessible like `require('pkg')` and
215+
`import 'pkg/module.mjs'`. Alternatively the package `"main"` could point to the
216+
ES module entry point and legacy users could be informed of the CommonJS entry
217+
point path, e.g. `require('pkg/commonjs')`.
219218

220219
## <code>import</code> Specifiers
221220

0 commit comments

Comments
 (0)