From c28ee9be88a46737f9d4b8df834459e3f3287bf4 Mon Sep 17 00:00:00 2001 From: Geoffrey Booth Date: Mon, 2 Sep 2019 21:12:13 -0700 Subject: [PATCH] doc: esm: expand discussion of publishing cjs/esm packages --- doc/api/esm.md | 63 ++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 48 insertions(+), 15 deletions(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index e3feb556569f3c..55fc48183c6093 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -97,14 +97,11 @@ if the nearest parent `package.json` contains `"type": "module"`. import './startup.js'; // Loaded as ES module because of package.json ``` -It is recommended that package authors always include the `"type"` field, even -in packages where it is unnecessary because all sources are CommonJS (and so -therefore the default `"type": "commonjs"` is implied) or because there are no -files ending in `.js` (for example, all files end in `.mjs` or `.cjs` or -`.wasm`, etc.). Being explicit about the `type` of the package will future-proof -the package in case Node.js’ default type ever changes, and it will also make -things easier for build tools and loaders to determine how the files in the -package should be interpreted. +Package authors should include the `"type"` field, even in packages where all +sources are CommonJS. Being explicit about the `type` of the package will +future-proof the package in case the default type of Node.js ever changes, and +it will also make things easier for build tools and loaders to determine how the +files in the package should be interpreted. ### Package Scope and File Extensions @@ -220,13 +217,48 @@ be interpreted as CommonJS. The `"main"` field can point to exactly one file, regardless of whether the package is referenced via `require` (in a CommonJS context) or `import` (in an -ES module context). Package authors who want to publish a package to be used in -both contexts can do so by setting `"main"` to point to the CommonJS entry point -and informing the package’s users of the path to the ES module entry point. Such -a package would be accessible like `require('pkg')` and `import -'pkg/module.mjs'`. Alternatively the package `"main"` could point to the ES -module entry point and legacy users could be informed of the CommonJS entry -point path, e.g. `require('pkg/commonjs')`. +ES module context). + +#### Compatibility with CommonJS-Only Versions of Node.js + +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) `"module"`. + +Node.js can now run ES module entry points, but it remains impossible for a +package to define separate CommonJS and ES module entry points. This is for good +reason: the `pkg` variable created from `import pkg from 'pkg'` is not the same +singleton as the `pkg` variable created from `const pkg = require('pkg')`, so if +both are referenced within the same app (including dependencies), unexpected +behavior might occur. + +There are two general approaches to addressing this limitation while still +publishing a package that contains both CommonJS and ES module sources: + +1. Document a new ES module entry point that’s not the package `"main"`, e.g. + `import pkg from 'pkg/module.mjs'` (or `import 'pkg/esm'`, if using [package + exports][]). The package `"main"` would still point to a CommonJS file, and + thus the package would remain compatible with older versions of Node.js that + lack support for ES modules. + +1. Switch the package `"main"` entry point to an ES module file as part of a + semver major version bump. This version and above would only be usable on ES + module-supporting versions of Node.js. If the package still contains a + CommonJS version, it would be accessible via a path within the package, e.g. + `require('pkg/commonjs')`; this is essentially the inverse of the previous + approach. Package consumers who are using CommonJS-only versions of Node.js + would need to update their code from `require('pkg')` to e.g. + `require('pkg/commonjs')`. + +Of course, a package could also include _only_ CommonJS or ES module sources. An +existing package could make a semver major bump to an ES module-only version, +that would only be supported in ES module-supporting versions of Node.js (and +other runtimes). New packages could be published containing only ES module +sources, and would be compatible only with ES module-supporting runtimes. ### Package Exports @@ -908,6 +940,7 @@ success! [CommonJS]: modules.html [ECMAScript-modules implementation]: https://github.com/nodejs/modules/blob/master/doc/plan-for-new-modules-implementation.md +[package exports]: #esm_package_exports [ES Module Integration Proposal for Web Assembly]: https://github.com/webassembly/esm-integration [Node.js EP for ES Modules]: https://github.com/nodejs/node-eps/blob/master/002-es-modules.md [Terminology]: #esm_terminology