@@ -455,7 +455,7 @@ ignores) the top-level `"module"` field.
455455
456456Node.js can now run ES module entry points, and a package can contain both
457457CommonJS 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
459459Exports] [ ] with the ` --experimental-conditional-exports ` flag). Unlike in the
460460scenario where ` "module" ` is only used by bundlers, or ES module files are
461461transpiled 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
466466When an application is using a package that provides both CommonJS and ES module
467467sources, 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
478479If the package main export is a constructor, an ` instanceof ` comparison of
479480instances 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
482483all-CommonJS or all-ES module environments, respectively, and therefore is
483484surprising to users. It also differs from the behavior users are familiar with
484485when using transpilation via tools like [ Babel] [ ] or [ ` esm ` ] [ ] .
0 commit comments