diff --git a/doc/api/esm.md b/doc/api/esm.md index 75547159d3a0ae..b2ca0f2b2848d7 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -60,7 +60,7 @@ or when referenced by `import` statements within ES module code: * Strings passed in as an argument to `--eval` or `--print`, or piped to `node` via `STDIN`, with the flag `--input-type=commonjs`. -## package.json "type" field +### package.json "type" field Files ending with `.js` or `.mjs`, or lacking any extension, will be loaded as ES modules when the nearest parent `package.json` file @@ -97,7 +97,13 @@ if the nearest parent `package.json` contains `"type": "module"`. import './startup.js'; // Loaded as ES module because of package.json ``` -## Package Scope and File Extensions +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 A folder containing a `package.json` file, and all subfolders below that folder down until the next folder containing another `package.json`, is @@ -156,7 +162,7 @@ package scope: extension (since both `.js` and `.cjs` files are treated as CommonJS within a `"commonjs"` package scope). -## --input-type flag +### --input-type flag Strings passed in as an argument to `--eval` or `--print` (or `-e` or `-p`), or piped to `node` via `STDIN`, will be treated as ES modules when the @@ -174,7 +180,9 @@ For completeness there is also `--input-type=commonjs`, for explicitly running string input as CommonJS. This is the default behavior if `--input-type` is unspecified. -## Package Entry Points +## Packages + +### Package Entry Points The `package.json` `"main"` field defines the entry point for a package, whether the package is included into CommonJS via `require` or into an ES @@ -209,15 +217,50 @@ 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')`. - -## Package Exports +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 + breaking change 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 only 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 By default, all subpaths from a package can be imported (`import 'pkg/x.js'`). Custom subpath aliasing and encapsulation can be provided through the @@ -930,5 +973,6 @@ success! [`import`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import [`module.createRequire()`]: modules.html#modules_module_createrequire_filename [dynamic instantiate hook]: #esm_dynamic_instantiate_hook +[package exports]: #esm_package_exports [special scheme]: https://url.spec.whatwg.org/#special-scheme [the official standard format]: https://tc39.github.io/ecma262/#sec-modules