From e17d3c19f512e0da6138a24cfa7b7c138687af7b Mon Sep 17 00:00:00 2001 From: Samual Norman Date: Fri, 29 Mar 2024 12:15:52 +0000 Subject: [PATCH 1/5] docs: document `package.json`'s `"exports"` field --- .../content/configuring-npm/package-json.md | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md index 51c516d5f37e8..b492dd179d1e3 100644 --- a/docs/lib/content/configuring-npm/package-json.md +++ b/docs/lib/content/configuring-npm/package-json.md @@ -339,6 +339,27 @@ not much else. If `main` is not set, it defaults to `index.js` in the package's root folder. +### exports + +The exports field is an object that maps entry points to modules. It supports wild cards (`*`) and explicit names. + +For example, you could have: + +```json +{ + "exports": { + ".": "./index.js", + "./*": "./*.js", + "./*.js": "./*.js", + "./foo": "./path/to/foo.js" + } +} +``` + +If someone installed your package with this in your `package.json`, they could `require("my-package")` and it would be mapped to `./node_modules/my-package/index.js` because of `".": "./index.js"`.
+If they did `require("my-package/bar")` or `require("my-package/bar.js")`, it would be mapped to `./node_modules/my-package/bar.js` because of the wild cards (`*`).
+If they did `require("my-package/foo")` it would be mapped to `./node_modules/my-package/path/to/foo.js` because of the explicit mapping `"./foo": "./path/to/foo.js"`.
+ ### browser If your module is meant to be used client-side the browser field should be From 7a38e9f0c4178ef6fe95586a661d56fdf5cb4acd Mon Sep 17 00:00:00 2001 From: Samual Date: Sat, 30 Mar 2024 14:06:50 +0000 Subject: [PATCH 2/5] docs: document `package.json`'s `"exports"` fields' conditional exports --- .../content/configuring-npm/package-json.md | 52 +++++++++++++++++-- 1 file changed, 47 insertions(+), 5 deletions(-) diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md index b492dd179d1e3..9e8d5b2f9aadb 100644 --- a/docs/lib/content/configuring-npm/package-json.md +++ b/docs/lib/content/configuring-npm/package-json.md @@ -341,7 +341,16 @@ If `main` is not set, it defaults to `index.js` in the package's root folder. ### exports -The exports field is an object that maps entry points to modules. It supports wild cards (`*`) and explicit names. +The exports field is an object that maps entry points to modules. This field is +supported by Node.js versions including and higher than 12. It acts as a more +featureful alternative to the main field. Each key can be an explicit path for +mapping entry points to modules 1 to 1, or it can include a wild card (`*`) for +mapping multiple entry points that fit the wild card to corrosponding modules. + +Each value in the exports field object can be an array of entry point string +where each path will be iterated through and the first path that leads to a +module will be used. The value also does not necessarily need to map to a +JavaScript module, it can also map to a JSON file. For example, you could have: @@ -351,14 +360,47 @@ For example, you could have: ".": "./index.js", "./*": "./*.js", "./*.js": "./*.js", - "./foo": "./path/to/foo.js" + "./foo": "./path/to/foo.js", + "./package.json": "./package.json" } } ``` -If someone installed your package with this in your `package.json`, they could `require("my-package")` and it would be mapped to `./node_modules/my-package/index.js` because of `".": "./index.js"`.
-If they did `require("my-package/bar")` or `require("my-package/bar.js")`, it would be mapped to `./node_modules/my-package/bar.js` because of the wild cards (`*`).
-If they did `require("my-package/foo")` it would be mapped to `./node_modules/my-package/path/to/foo.js` because of the explicit mapping `"./foo": "./path/to/foo.js"`.
+If someone installed your package with this in your `package.json`, they could +`require("my-package")` and it would be mapped to +`./node_modules/my-package/index.js` because of `".": "./index.js"`.
+If they did `require("my-package/bar")` or `require("my-package/bar.js")`, it +would be mapped to `./node_modules/my-package/bar.js` because of the wild cards +(`*`).
+If they did `require("my-package/foo")` it would be mapped to +`./node_modules/my-package/path/to/foo.js` because of the explicit mapping +`"./foo": "./path/to/foo.js"`. + +The exports field also supports conditional exports, which will use a different +object to resolve entry points to modules depending on if the consumer of your +package is using CommonJS `require()` calls or ESM `import` +statements/expressions. + +Here is an example of conditional exports: + +```json + "exports": { + "require": { + ".": "./index.cjs", + "./*": "./*.cjs", + "./*.js": "./*.cjs", + "./foo": "./path/to/foo.cjs", + "./package.json": "./package.json" + }, + "import": { + ".": "./index.js", + "./*": "./*.js", + "./*.js": "./*.js", + "./foo": "./path/to/foo.js", + "./package.json": "./package.json" + } + } +``` ### browser From 7cb514a3fe4bc2736c712dd2a434c44d02932a98 Mon Sep 17 00:00:00 2001 From: Samual Date: Sat, 30 Mar 2024 20:51:09 +0000 Subject: [PATCH 3/5] docs: make comment about `package.json` `"exports"` field support more generic --- docs/lib/content/configuring-npm/package-json.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md index 9e8d5b2f9aadb..89585248dff5a 100644 --- a/docs/lib/content/configuring-npm/package-json.md +++ b/docs/lib/content/configuring-npm/package-json.md @@ -342,10 +342,10 @@ If `main` is not set, it defaults to `index.js` in the package's root folder. ### exports The exports field is an object that maps entry points to modules. This field is -supported by Node.js versions including and higher than 12. It acts as a more -featureful alternative to the main field. Each key can be an explicit path for -mapping entry points to modules 1 to 1, or it can include a wild card (`*`) for -mapping multiple entry points that fit the wild card to corrosponding modules. +only supported by modern Node.js versions. It acts as a more featureful +alternative to the main field. Each key can be an explicit path for mapping +entry points to modules 1 to 1, or it can include a wild card (`*`) for mapping +multiple entry points that fit the wild card to corrosponding modules. Each value in the exports field object can be an array of entry point string where each path will be iterated through and the first path that leads to a From 5be8cc1e72906ebd04dda60c97d124c126483486 Mon Sep 17 00:00:00 2001 From: Samual Date: Sat, 30 Mar 2024 20:52:52 +0000 Subject: [PATCH 4/5] docs: add examples for `package.json` `"exports"` field fallbacks --- docs/lib/content/configuring-npm/package-json.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md index 89585248dff5a..69ba04f99a1d3 100644 --- a/docs/lib/content/configuring-npm/package-json.md +++ b/docs/lib/content/configuring-npm/package-json.md @@ -361,7 +361,8 @@ For example, you could have: "./*": "./*.js", "./*.js": "./*.js", "./foo": "./path/to/foo.js", - "./package.json": "./package.json" + "./package.json": "./package.json", + "./baz": [ "./try-here.js", "./then-try-here.js" ] } } ``` @@ -390,14 +391,16 @@ Here is an example of conditional exports: "./*": "./*.cjs", "./*.js": "./*.cjs", "./foo": "./path/to/foo.cjs", - "./package.json": "./package.json" + "./package.json": "./package.json", + "./baz": [ "./try-here.cjs", "./then-try-here.cjs" ] }, "import": { ".": "./index.js", "./*": "./*.js", "./*.js": "./*.js", "./foo": "./path/to/foo.js", - "./package.json": "./package.json" + "./package.json": "./package.json", + "./baz": [ "./try-here.js", "./then-try-here.js" ] } } ``` From d3acde9cd063ff7eca3c30168d2ddaaac376d3a9 Mon Sep 17 00:00:00 2001 From: Samual Date: Sat, 30 Mar 2024 20:56:44 +0000 Subject: [PATCH 5/5] docs: add link to official Node.js docs on `package.json` `"exports"` field --- docs/lib/content/configuring-npm/package-json.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md index 69ba04f99a1d3..4440772dc692e 100644 --- a/docs/lib/content/configuring-npm/package-json.md +++ b/docs/lib/content/configuring-npm/package-json.md @@ -405,6 +405,10 @@ Here is an example of conditional exports: } ``` +More information on the exports field can be found +[on the Node.js Docs](https://nodejs.org/docs/latest/api/packages.html#package-entry-points) +. + ### browser If your module is meant to be used client-side the browser field should be