Skip to content

Commit

Permalink
doc: rename for clarity
Browse files Browse the repository at this point in the history
  • Loading branch information
GeoffreyBooth committed Nov 14, 2019
1 parent 2637f4d commit 4b75b64
Showing 1 changed file with 13 additions and 12 deletions.
25 changes: 13 additions & 12 deletions doc/api/esm.md
Expand Up @@ -455,7 +455,7 @@ ignores) the top-level `"module"` field.

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

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

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

0 comments on commit 4b75b64

Please sign in to comment.