doc: document self-referencing a package name

giltayar · MylesBorins · commit 97965f518c31 · 2020-03-09T19:02:23.000-04:00
Added a section for "Self-referencing a package using its name" that documents importing a package's own exports (this was missed when adding the feature). PR-URL: #31680 Reviewed-By: Jan Krems <jan.krems@gmail.com> Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com>
diff --git a/doc/api/esm.md b/doc/api/esm.md
@@ -431,6 +431,51 @@ thrown:
 }
 ```
 
+#### Self-referencing a package using its name
+
+Within a package, the values defined in the package’s
+`package.json` `"exports"` field can be referenced via the package’s name.
+For example, assuming the `package.json` is:
+
+```json
+// package.json
+{
+  "name": "a-package",
+  "exports": {
+    ".": "./main.mjs",
+    "./foo": "./foo.js"
+  }
+}
+```
+
+Then any module _in that package_ can reference an export in the package itself:
+
+```js
+// ./a-module.mjs
+import { something } from 'a-package'; // Imports "something" from ./main.mjs.
+```
+
+Self-referencing is available only if `package.json` has `exports`, and will
+allow importing only what that `exports` (in the `package.json`) allows.
+So the code below, given the package above, will generate a runtime error:
+
+```js
+// ./another-module.mjs
+
+// Imports "another" from ./m.mjs. Fails because
+// the "package.json" "exports" field
+// does not provide an export named "./m.mjs".
+import { another } from 'a-package/m.mjs';
+```
+
+Self-referencing is also available when using `require`, both in an ES module,
+and in a CommonJS one. For example, this code will also work:
+
+```js
+// ./a-module.js
+const { something } = require('a-package/foo'); // Loads from ./foo.js.
+```
+
 ### Dual CommonJS/ES Module Packages
 
 Prior to the introduction of support for ES modules in Node.js, it was a common
