Skip to content

Commit 4b75b64

Browse files
committed
doc: rename for clarity
1 parent 2637f4d commit 4b75b64

File tree

1 file changed

+13
-12
lines changed

1 file changed

+13
-12
lines changed

doc/api/esm.md

+13-12
Original file line numberDiff line numberDiff line change
@@ -455,7 +455,7 @@ ignores) the top-level `"module"` field.
455455

456456
Node.js can now run ES module entry points, and a package can contain both
457457
CommonJS and ES module entry points (either via separate specifiers such as
458-
`'pkg'` and `'pkg/module'`, or both at the same specifier via [Conditional
458+
`'pkg'` and `'pkg/es-module'`, or both at the same specifier via [Conditional
459459
Exports][] with the `--experimental-conditional-exports` flag). Unlike in the
460460
scenario where `"module"` is only used by bundlers, or ES module files are
461461
transpiled into CommonJS on the fly before evaluation by Node.js, the files
@@ -465,20 +465,21 @@ referenced by the ES module entry point are evaluated as ES modules.
465465

466466
When an application is using a package that provides both CommonJS and ES module
467467
sources, there is a risk of certain bugs if both versions of the package get
468-
loaded. This potential comes from the fact that the `pkg` created by `const pkg
469-
= require('pkg')` is not the same as the `pkg` created by `import pkg from
470-
'pkg'` (or an alternative main path like `'pkg/module'`). This is the “dual
471-
package hazard,” where two versions of the same package can be loaded within the
472-
same runtime environment. While it is unlikely that an application or package
473-
would intentionally load both versions directly, it is common for an application
474-
to load one version while a dependency of the application loads the other
475-
version. This hazard can happen because Node.js supports intermixing CommonJS
476-
and ES modules, and can lead to unexpected behavior.
468+
loaded. This potential comes from the fact that the `pkgInstance` created by
469+
`const pkgInstance = require('pkg')` is not the same as the `pkgInstance`
470+
created by `import pkgInstance from 'pkg'` (or an alternative main path like
471+
`'pkg/module'`). This is the “dual package hazard,” where two versions of the
472+
same package can be loaded within the same runtime environment. While it is
473+
unlikely that an application or package would intentionally load both versions
474+
directly, it is common for an application to load one version while a dependency
475+
of the application loads the other version. This hazard can happen because
476+
Node.js supports intermixing CommonJS and ES modules, and can lead to unexpected
477+
behavior.
477478

478479
If the package main export is a constructor, an `instanceof` comparison of
479480
instances created by the two versions returns `false`, and if the export is an
480-
object, properties added to one (like `pkg.foo = 3`) are not present on the
481-
other. This differs from how `import` and `require` statements work in
481+
object, properties added to one (like `pkgInstance.foo = 3`) are not present on
482+
the other. This differs from how `import` and `require` statements work in
482483
all-CommonJS or all-ES module environments, respectively, and therefore is
483484
surprising to users. It also differs from the behavior users are familiar with
484485
when using transpilation via tools like [Babel][] or [`esm`][].

0 commit comments

Comments
 (0)