doc: move dual package shipping docs to separate repo

joyeecheung · marco-ippolito · commit 8e76cc69e5da · 2025-03-06T13:38:01.000+01:00
Refs: nodejs/admin#917 Refs: nodejs/package-examples#1 Refs: #54648 PR-URL: #55444 Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
diff --git a/doc/api/packages.md b/doc/api/packages.md
@@ -902,273 +902,7 @@ $ node other.js
 
 ## Dual CommonJS/ES module packages
 
-<!-- This section should not be in the API documentation:
-
-1. It teaches opinionated practices that some consider dangerous, see
-   https://github.com/nodejs/node/issues/52174
-2. It will soon be obsolete when we unflag --experimental-require-module.
-3. It's difficult to understand a multi-file structure via long texts and snippets in
-   a markdown document.
-
-TODO(?): Move this section to its own repository with example folders.
--->
-
-Prior to the introduction of support for ES modules in Node.js, it was a common
-pattern for package authors to include both CommonJS and ES module JavaScript
-sources in their package, with `package.json` [`"main"`][] specifying the
-CommonJS entry point and `package.json` `"module"` specifying the ES module
-entry point.
-This enabled Node.js to run the CommonJS entry point while build tools such as
-bundlers used the ES module entry point, since Node.js ignored (and still
-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/es-module'`, or both at the same specifier via [Conditional
-exports][]). Unlike in the scenario where top-level `"module"` field is only used by bundlers,
-or ES module files are transpiled into CommonJS on the fly before evaluation by
-Node.js, the files referenced by the ES module entry point are evaluated as ES
-modules.
-
-### Dual package hazard
-
-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 `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 &ldquo;dual package hazard,&rdquo; 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 `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`][].
-
-### Writing dual packages while avoiding or minimizing hazards
-
-First, the hazard described in the previous section occurs when a package
-contains both CommonJS and ES module sources and both sources are provided for
-use in Node.js, either via separate main entry points or exported paths. A
-package might instead be written where any version of Node.js receives only
-CommonJS sources, and any separate ES module sources the package might contain
-are intended only for other environments such as browsers. Such a package
-would be usable by any version of Node.js, since `import` can refer to CommonJS
-files; but it would not provide any of the advantages of using ES module syntax.
-
-A package might also switch from CommonJS to ES module syntax in a [breaking
-change](https://semver.org/) version bump. This has the disadvantage that the
-newest version of the package would only be usable in ES module-supporting
-versions of Node.js.
-
-Every pattern has tradeoffs, but there are two broad approaches that satisfy the
-following conditions:
-
-1. The package is usable via both `require` and `import`.
-2. The package is usable in both current Node.js and older versions of Node.js
-   that lack support for ES modules.
-3. The package main entry point, e.g. `'pkg'` can be used by both `require` to
-   resolve to a CommonJS file and by `import` to resolve to an ES module file.
-   (And likewise for exported paths, e.g. `'pkg/feature'`.)
-4. The package provides named exports, e.g. `import { name } from 'pkg'` rather
-   than `import pkg from 'pkg'; pkg.name`.
-5. The package is potentially usable in other ES module environments such as
-   browsers.
-6. The hazards described in the previous section are avoided or minimized.
-
-#### Approach #1: Use an ES module wrapper
-
-Write the package in CommonJS or transpile ES module sources into CommonJS, and
-create an ES module wrapper file that defines the named exports. Using
-[Conditional exports][], the ES module wrapper is used for `import` and the
-CommonJS entry point for `require`.
-
-```json
-// ./node_modules/pkg/package.json
-{
-  "type": "module",
-  "exports": {
-    "import": "./wrapper.mjs",
-    "require": "./index.cjs"
-  }
-}
-```
-
-The preceding example uses explicit extensions `.mjs` and `.cjs`.
-If your files use the `.js` extension, `"type": "module"` will cause such files
-to be treated as ES modules, just as `"type": "commonjs"` would cause them
-to be treated as CommonJS.
-See [Enabling](esm.md#enabling).
-
-```cjs
-// ./node_modules/pkg/index.cjs
-exports.name = 'value';
-```
-
-```js
-// ./node_modules/pkg/wrapper.mjs
-import cjsModule from './index.cjs';
-export const name = cjsModule.name;
-```
-
-In this example, the `name` from `import { name } from 'pkg'` is the same
-singleton as the `name` from `const { name } = require('pkg')`. Therefore `===`
-returns `true` when comparing the two `name`s and the divergent specifier hazard
-is avoided.
-
-If the module is not simply a list of named exports, but rather contains a
-unique function or object export like `module.exports = function () { ... }`,
-or if support in the wrapper for the `import pkg from 'pkg'` pattern is desired,
-then the wrapper would instead be written to export the default optionally
-along with any named exports as well:
-
-```js
-import cjsModule from './index.cjs';
-export const name = cjsModule.name;
-export default cjsModule;
-```
-
-This approach is appropriate for any of the following use cases:
-
-* The package is currently written in CommonJS and the author would prefer not
-  to refactor it into ES module syntax, but wishes to provide named exports for
-  ES module consumers.
-* The package has other packages that depend on it, and the end user might
-  install both this package and those other packages. For example a `utilities`
-  package is used directly in an application, and a `utilities-plus` package
-  adds a few more functions to `utilities`. Because the wrapper exports
-  underlying CommonJS files, it doesn't matter if `utilities-plus` is written in
-  CommonJS or ES module syntax; it will work either way.
-* The package stores internal state, and the package author would prefer not to
-  refactor the package to isolate its state management. See the next section.
-
-A variant of this approach not requiring conditional exports for consumers could
-be to add an export, e.g. `"./module"`, to point to an all-ES module-syntax
-version of the package. This could be used via `import 'pkg/module'` by users
-who are certain that the CommonJS version will not be loaded anywhere in the
-application, such as by dependencies; or if the CommonJS version can be loaded
-but doesn't affect the ES module version (for example, because the package is
-stateless):
-
-```json
-// ./node_modules/pkg/package.json
-{
-  "type": "module",
-  "exports": {
-    ".": "./index.cjs",
-    "./module": "./wrapper.mjs"
-  }
-}
-```
-
-#### Approach #2: Isolate state
-
-A [`package.json`][] file can define the separate CommonJS and ES module entry
-points directly:
-
-```json
-// ./node_modules/pkg/package.json
-{
-  "type": "module",
-  "exports": {
-    "import": "./index.mjs",
-    "require": "./index.cjs"
-  }
-}
-```
-
-This can be done if both the CommonJS and ES module versions of the package are
-equivalent, for example because one is the transpiled output of the other; and
-the package's management of state is carefully isolated (or the package is
-stateless).
-
-The reason that state is an issue is because both the CommonJS and ES module
-versions of the package might get used within an application; for example, the
-user's application code could `import` the ES module version while a dependency
-`require`s the CommonJS version. If that were to occur, two copies of the
-package would be loaded in memory and therefore two separate states would be
-present. This would likely cause hard-to-troubleshoot bugs.
-
-Aside from writing a stateless package (if JavaScript's `Math` were a package,
-for example, it would be stateless as all of its methods are static), there are
-some ways to isolate state so that it's shared between the potentially loaded
-CommonJS and ES module instances of the package:
-
-1. If possible, contain all state within an instantiated object. JavaScript's
-   `Date`, for example, needs to be instantiated to contain state; if it were a
-   package, it would be used like this:
-
-   ```js
-   import Date from 'date';
-   const someDate = new Date();
-   // someDate contains state; Date does not
-   ```
-
-   The `new` keyword isn't required; a package's function can return a new
-   object, or modify a passed-in object, to keep the state external to the
-   package.
-
-2. Isolate the state in one or more CommonJS files that are shared between the
-   CommonJS and ES module versions of the package. For example, if the CommonJS
-   and ES module entry points are `index.cjs` and `index.mjs`, respectively:
-
-   ```cjs
-   // ./node_modules/pkg/index.cjs
-   const state = require('./state.cjs');
-   module.exports.state = state;
-   ```
-
-   ```js
-   // ./node_modules/pkg/index.mjs
-   import state from './state.cjs';
-   export {
-     state,
-   };
-   ```
-
-   Even if `pkg` is used via both `require` and `import` in an application (for
-   example, via `import` in application code and via `require` by a dependency)
-   each reference of `pkg` will contain the same state; and modifying that
-   state from either module system will apply to both.
-
-Any plugins that attach to the package's singleton would need to separately
-attach to both the CommonJS and ES module singletons.
-
-This approach is appropriate for any of the following use cases:
-
-* The package is currently written in ES module syntax and the package author
-  wants that version to be used wherever such syntax is supported.
-* The package is stateless or its state can be isolated without too much
-  difficulty.
-* The package is unlikely to have other public packages that depend on it, or if
-  it does, the package is stateless or has state that need not be shared between
-  dependencies or with the overall application.
-
-Even with isolated state, there is still the cost of possible extra code
-execution between the CommonJS and ES module versions of a package.
-
-As with the previous approach, a variant of this approach not requiring
-conditional exports for consumers could be to add an export, e.g.
-`"./module"`, to point to an all-ES module-syntax version of the package:
-
-```json
-// ./node_modules/pkg/package.json
-{
-  "type": "module",
-  "exports": {
-    ".": "./index.cjs",
-    "./module": "./index.mjs"
-  }
-}
-```
+See [the package examples repository][] for details.
 
 ## Node.js `package.json` field definitions
 
@@ -1412,7 +1146,6 @@ Package imports permit mapping to external packages.
 
 This field defines [subpath imports][] for the current package.
 
-[Babel]: https://babeljs.io/
 [CommonJS]: modules.md
 [Conditional exports]: #conditional-exports
 [Corepack]: corepack.md
@@ -1432,7 +1165,6 @@ This field defines [subpath imports][] for the current package.
 [`--experimental-default-type`]: cli.md#--experimental-default-typetype
 [`--no-addons` flag]: cli.md#--no-addons
 [`ERR_PACKAGE_PATH_NOT_EXPORTED`]: errors.md#err_package_path_not_exported
-[`esm`]: https://github.com/standard-things/esm#readme
 [`package.json`]: #nodejs-packagejson-field-definitions
 [entry points]: #package-entry-points
 [folders as modules]: modules.md#folders-as-modules
@@ -1446,3 +1178,4 @@ This field defines [subpath imports][] for the current package.
 [supported package managers]: corepack.md#supported-package-managers
 [the dual CommonJS/ES module packages section]: #dual-commonjses-module-packages
 [the full specifier path]: esm.md#mandatory-file-extensions
+[the package examples repository]: https://github.com/nodejs/package-examples
