doc: update outdated commonjs compat info

GeoffreyBooth · MylesBorins · commit 6ac1b1319298 · 2020-01-12T03:15:36.000-05:00
PR-URL: #30512 Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
diff --git a/doc/api/esm.md b/doc/api/esm.md
@@ -807,9 +807,9 @@ To include an ES module into CommonJS, use [`import()`][].
 
 ### `import` statements
 
-An `import` statement can reference an ES module, a CommonJS module, or JSON.
-Other file types such as Native modules are not supported. For those,
-use [`module.createRequire()`][].
+An `import` statement can reference an ES module or a CommonJS module. Other
+file types such as JSON or Native modules are not supported. For those, use
+[`module.createRequire()`][].
 
 `import` statements are permitted only in ES modules. For similar functionality
 in CommonJS, see [`import()`][].
@@ -819,23 +819,22 @@ can either be an URL-style relative path like `'./file.mjs'` or a package name
 like `'fs'`.
 
 Like in CommonJS, files within packages can be accessed by appending a path to
-the package name.
+the package name; unless the package’s `package.json` contains an [`"exports"`
+field][], in which case files within packages need to be accessed via the path
+defined in `"exports"`.
 
 ```js
 import { sin, cos } from 'geometry/trigonometry-functions.mjs';
 ```
 
-> Currently only the “default export” is supported for CommonJS files or
-> packages:
->
-> <!-- eslint-disable no-duplicate-imports -->
-> ```js
-> import packageMain from 'commonjs-package'; // Works
->
-> import { method } from 'commonjs-package'; // Errors
-> ```
->
-> There are ongoing efforts to make the latter code possible.
+Only the “default export” is supported for CommonJS files or packages:
+
+<!-- eslint-disable no-duplicate-imports -->
+```js
+import packageMain from 'commonjs-package'; // Works
+
+import { method } from 'commonjs-package'; // Errors
+```
 
 ### `import()` expressions
 
@@ -1366,6 +1365,7 @@ success!
 [Node.js EP for ES Modules]: https://github.com/nodejs/node-eps/blob/master/002-es-modules.md
 [Terminology]: #esm_terminology
 [WHATWG JSON modules specification]: https://html.spec.whatwg.org/#creating-a-json-module-script
+[`"exports"` field]: #esm_package_exports
 [`data:` URLs]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs
 [`esm`]: https://github.com/standard-things/esm#readme
 [`export`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export
