@@ -455,7 +455,7 @@ ignores) the top-level `"module"` field.
455
455
456
456
Node.js can now run ES module entry points, and a package can contain both
457
457
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
459
459
Exports] [ ] with the ` --experimental-conditional-exports ` flag). Unlike in the
460
460
scenario where ` "module" ` is only used by bundlers, or ES module files are
461
461
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.
465
465
466
466
When an application is using a package that provides both CommonJS and ES module
467
467
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.
477
478
478
479
If the package main export is a constructor, an ` instanceof ` comparison of
479
480
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
482
483
all-CommonJS or all-ES module environments, respectively, and therefore is
483
484
surprising to users. It also differs from the behavior users are familiar with
484
485
when using transpilation via tools like [ Babel] [ ] or [ ` esm ` ] [ ] .
0 commit comments