From 4e4f086794be10b33e721749f579615d5ba3799e Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Sun, 26 Apr 2020 02:47:31 -0400 Subject: [PATCH 01/24] doc: explicitly doc package.exports is breaking If package authors don't explicitly include all previously supported entry points introducing package.exports will be a Semver-Major change. Add a warning about this behavior and offer two potential solutions for module authors. Refs: https://github.com/then/is-promise/issues/20 --- doc/api/esm.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/api/esm.md b/doc/api/esm.md index 49c467effbc3cd..fd2c0a095df0cb 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -191,6 +191,12 @@ also be used within `"exports"` to define different package entry points per environment, including whether the package is referenced via `require` or via `import`. +***Warning***: Introducing the exports field prevents consumers of a package +for using any entry points that is not defined, including the `package.json`. +This is a Semver-Major change. To make the introduction of `"exports"` +Semver-Minor either ensure that every previously supported entry point is +exported or include a export of the root of the package `"./"; "./"`. + If both `"exports"` and `"main"` are defined, the `"exports"` field takes precedence over `"main"`. From 1068cfb57b0cff43adf42a8cedf8d68ab82f3718 Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Sun, 26 Apr 2020 22:14:20 -0400 Subject: [PATCH 02/24] Update doc/api/esm.md Co-Authored-By: Mark Wubben --- doc/api/esm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index fd2c0a095df0cb..2c325493cff59a 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -192,7 +192,7 @@ environment, including whether the package is referenced via `require` or via `import`. ***Warning***: Introducing the exports field prevents consumers of a package -for using any entry points that is not defined, including the `package.json`. +from using any entry points that are not defined, including the `package.json`. This is a Semver-Major change. To make the introduction of `"exports"` Semver-Minor either ensure that every previously supported entry point is exported or include a export of the root of the package `"./"; "./"`. From c1f5310dec7c0c7037e5ae69e0f525b24041d86e Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Sun, 26 Apr 2020 22:14:33 -0400 Subject: [PATCH 03/24] Update doc/api/esm.md Co-Authored-By: Mark Wubben --- doc/api/esm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index 2c325493cff59a..4bbf6dc51e7554 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -195,7 +195,7 @@ environment, including whether the package is referenced via `require` or via from using any entry points that are not defined, including the `package.json`. This is a Semver-Major change. To make the introduction of `"exports"` Semver-Minor either ensure that every previously supported entry point is -exported or include a export of the root of the package `"./"; "./"`. +exported or include an export of the root of the package `"./": "./"`. If both `"exports"` and `"main"` are defined, the `"exports"` field takes precedence over `"main"`. From dd2ba5b79e896bb3e3a528f023b1e7ed7b282db5 Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Sun, 26 Apr 2020 22:14:50 -0400 Subject: [PATCH 04/24] Update doc/api/esm.md Co-Authored-By: Geoffrey Booth --- doc/api/esm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index 4bbf6dc51e7554..cc6d857fab87a1 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -191,7 +191,7 @@ also be used within `"exports"` to define different package entry points per environment, including whether the package is referenced via `require` or via `import`. -***Warning***: Introducing the exports field prevents consumers of a package +**Warning**: Introducing the `"exports"` field prevents consumers of a package from using any entry points that are not defined, including the `package.json`. This is a Semver-Major change. To make the introduction of `"exports"` Semver-Minor either ensure that every previously supported entry point is From 0fc7b73e0671e337d5a52539c00d8b65da12ba82 Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Sun, 26 Apr 2020 22:14:59 -0400 Subject: [PATCH 05/24] Update doc/api/esm.md Co-Authored-By: Geoffrey Booth --- doc/api/esm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index cc6d857fab87a1..26f761a947fe69 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -193,7 +193,7 @@ environment, including whether the package is referenced via `require` or via **Warning**: Introducing the `"exports"` field prevents consumers of a package from using any entry points that are not defined, including the `package.json`. -This is a Semver-Major change. To make the introduction of `"exports"` +This will likely be a breaking change. To make the introduction of `"exports"` Semver-Minor either ensure that every previously supported entry point is exported or include an export of the root of the package `"./": "./"`. From 5508ad8f95eb9ac5d7f765bb449296d794664c99 Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Sun, 26 Apr 2020 22:15:05 -0400 Subject: [PATCH 06/24] Update doc/api/esm.md Co-Authored-By: Geoffrey Booth --- doc/api/esm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index 26f761a947fe69..ca288999675d5c 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -194,7 +194,7 @@ environment, including whether the package is referenced via `require` or via **Warning**: Introducing the `"exports"` field prevents consumers of a package from using any entry points that are not defined, including the `package.json`. This will likely be a breaking change. To make the introduction of `"exports"` -Semver-Minor either ensure that every previously supported entry point is +non-breaking, either ensure that every previously supported entry point is exported or include an export of the root of the package `"./": "./"`. If both `"exports"` and `"main"` are defined, the `"exports"` field takes From 2acd4262109229266872d94e6fdf8f1a0a201e36 Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Mon, 27 Apr 2020 23:35:29 -0400 Subject: [PATCH 07/24] Update doc/api/esm.md Co-Authored-By: Rob Palmer --- doc/api/esm.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index ca288999675d5c..630154def0c1b2 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -194,8 +194,10 @@ environment, including whether the package is referenced via `require` or via **Warning**: Introducing the `"exports"` field prevents consumers of a package from using any entry points that are not defined, including the `package.json`. This will likely be a breaking change. To make the introduction of `"exports"` -non-breaking, either ensure that every previously supported entry point is -exported or include an export of the root of the package `"./": "./"`. +non-breaking, ensure that every previously supported entry point is exported. +It is best to explicitly specify entry points so that the package's public API is +well-defined. As a last resort, package encapsulation can be disabled entirely by +creating an export for the root of the package `"./": "./"` that will expose every file. If both `"exports"` and `"main"` are defined, the `"exports"` field takes precedence over `"main"`. From d059abf5e87fea86f706aedb45e5dcdf2553419e Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Wed, 29 Apr 2020 10:59:43 -0400 Subject: [PATCH 08/24] Update esm.md --- doc/api/esm.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index 630154def0c1b2..f2542fd3c3fa32 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -195,9 +195,10 @@ environment, including whether the package is referenced via `require` or via from using any entry points that are not defined, including the `package.json`. This will likely be a breaking change. To make the introduction of `"exports"` non-breaking, ensure that every previously supported entry point is exported. -It is best to explicitly specify entry points so that the package's public API is -well-defined. As a last resort, package encapsulation can be disabled entirely by -creating an export for the root of the package `"./": "./"` that will expose every file. +It is best to explicitly specify entry points so that the package's public API +is well-defined. As a last resort, package encapsulation can be disabled +entirely by creating an export for the root of the package `"./": "./"` that +will expose every file. If both `"exports"` and `"main"` are defined, the `"exports"` field takes precedence over `"main"`. From 3785420cfc84d4ebe7c900cfcecf3aec661cf4e8 Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Wed, 29 Apr 2020 11:14:08 -0400 Subject: [PATCH 09/24] fixup: lots of changes --- doc/api/esm.md | 54 +++++++++++++++++++++++++++++++------------------- 1 file changed, 34 insertions(+), 20 deletions(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index f2542fd3c3fa32..bf9dbeba3b6c3a 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -183,34 +183,48 @@ versions of Node.js, but its capabilities are limited: it only defines the main entry point of the package. The `"exports"` field provides an alternative to `"main"` where the package -main entry point can be defined while also encapsulating the package, preventing -any other entry points besides those defined in `"exports"`. If package entry -points are defined in both `"main"` and `"exports"`, the latter takes precedence -in versions of Node.js that support `"exports"`. [Conditional Exports][] can -also be used within `"exports"` to define different package entry points per -environment, including whether the package is referenced via `require` or via -`import`. +main entry point can be defined while also encapsulating the package, +**preventing any other entry points besides those defined in `"exports"`**. +This encapsulation allows module authors to define a public interface for +their package + +If both `"exports"` and `"main"` are defined, the `"exports"` field takes +precedence over `"main"`. It is important to note that `"exports"` are not +specific to ES modules or CommonJS; `"main"` will be overridden by `"exports"` +if it exists. As such `"main"` cannot be used as a fallback for `"Common.js"` +but it can be used as a fallback for legacy versions of Node.js that do not +support ES Modules. + +[Conditional Exports][] can be used within `"exports"` to define different +package entry points per environment, including whether the package is +referenced via `require` or via `import`. For more information about supporting +both Common.js and ES Modules in a single package please consult +[the dual CommonJS/ES module packages section][]. **Warning**: Introducing the `"exports"` field prevents consumers of a package from using any entry points that are not defined, including the `package.json`. This will likely be a breaking change. To make the introduction of `"exports"` non-breaking, ensure that every previously supported entry point is exported. It is best to explicitly specify entry points so that the package's public API -is well-defined. As a last resort, package encapsulation can be disabled -entirely by creating an export for the root of the package `"./": "./"` that -will expose every file. +is well-defined. For example, a project that previous exported `main`, `lib`, +`feature`, and the `package.json` could use the following `package.exports` -If both `"exports"` and `"main"` are defined, the `"exports"` field takes -precedence over `"main"`. - -Both `"main"` and `"exports"` entry points are not specific to ES modules or -CommonJS; `"main"` will be overridden by `"exports"` in a `require` so it is -not a CommonJS fallback. +```json +{ + "exports": { + ".": "./lib/index.js", + "./lib": "./lib/index.js", + "./lib/index.js": "./lib/index.js", + "./feature": "./feature/index.js", + "./feature/index.js": "./feature/index.js", + "./package.json": "./package.json" + } +} +``` -This is important with regard to `require`, since `require` of ES module files -throws an error in all versions of Node.js. To create a package that works both -in modern Node.js via `import` and `require` and also legacy Node.js versions, -see [the dual CommonJS/ES module packages section][]. +As a last resort, package encapsulation can be disabled entirely by creating an +export for the root of the package `"./": "./"`. This will expose every file in +the package at the cost of disabling encapsulation. #### Main Entry Point Export From c3b6f2fc3f31a48cc7711a1d45605917fd68a56f Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Fri, 1 May 2020 01:05:38 -0400 Subject: [PATCH 10/24] Update doc/api/esm.md Co-authored-by: Guy Bedford --- doc/api/esm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index bf9dbeba3b6c3a..dcbfc43b5fe5c3 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -191,7 +191,7 @@ their package If both `"exports"` and `"main"` are defined, the `"exports"` field takes precedence over `"main"`. It is important to note that `"exports"` are not specific to ES modules or CommonJS; `"main"` will be overridden by `"exports"` -if it exists. As such `"main"` cannot be used as a fallback for `"Common.js"` +if it exists. As such `"main"` cannot be used as a fallback for CommonJS but it can be used as a fallback for legacy versions of Node.js that do not support ES Modules. From e7937e86fc3c8efbea90b5382b28b93ee52d959f Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Fri, 1 May 2020 01:05:55 -0400 Subject: [PATCH 11/24] Update doc/api/esm.md Co-authored-by: Guy Bedford --- doc/api/esm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index dcbfc43b5fe5c3..f0f4f103d49f07 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -193,7 +193,7 @@ precedence over `"main"`. It is important to note that `"exports"` are not specific to ES modules or CommonJS; `"main"` will be overridden by `"exports"` if it exists. As such `"main"` cannot be used as a fallback for CommonJS but it can be used as a fallback for legacy versions of Node.js that do not -support ES Modules. +support the exports field. [Conditional Exports][] can be used within `"exports"` to define different package entry points per environment, including whether the package is From 7e1ac3a8221ecfd855cccb689a059759f727fa11 Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Fri, 1 May 2020 01:06:02 -0400 Subject: [PATCH 12/24] Update doc/api/esm.md Co-authored-by: Guy Bedford --- doc/api/esm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index f0f4f103d49f07..230009526f4b93 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -207,7 +207,7 @@ This will likely be a breaking change. To make the introduction of `"exports"` non-breaking, ensure that every previously supported entry point is exported. It is best to explicitly specify entry points so that the package's public API is well-defined. For example, a project that previous exported `main`, `lib`, -`feature`, and the `package.json` could use the following `package.exports` +`feature`, and the `package.json` could use the following `package.exports`: ```json { From a1f478121a5ce7837b8f9860bc6f292014270f0e Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Fri, 1 May 2020 01:06:25 -0400 Subject: [PATCH 13/24] Update doc/api/esm.md Co-authored-by: Guy Bedford --- doc/api/esm.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index 230009526f4b93..16547ec23f6cd1 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -224,7 +224,8 @@ is well-defined. For example, a project that previous exported `main`, `lib`, As a last resort, package encapsulation can be disabled entirely by creating an export for the root of the package `"./": "./"`. This will expose every file in -the package at the cost of disabling encapsulation. +the package at the cost of disabling encapsulation and the tooling and optimization +benefits that come with it. #### Main Entry Point Export From c4ec3b1a377bc36ffd53d8895509c6bbb3add088 Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Fri, 1 May 2020 09:42:10 -0400 Subject: [PATCH 14/24] Update doc/api/esm.md Co-authored-by: Geoffrey Booth --- doc/api/esm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index 16547ec23f6cd1..13cd62f51bdeb2 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -186,7 +186,7 @@ The `"exports"` field provides an alternative to `"main"` where the package main entry point can be defined while also encapsulating the package, **preventing any other entry points besides those defined in `"exports"`**. This encapsulation allows module authors to define a public interface for -their package +their package. If both `"exports"` and `"main"` are defined, the `"exports"` field takes precedence over `"main"`. It is important to note that `"exports"` are not From fd65c2d15ab282a56edd1d39d912f4bb41967a13 Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Fri, 1 May 2020 09:42:25 -0400 Subject: [PATCH 15/24] Update doc/api/esm.md Co-authored-by: Geoffrey Booth --- doc/api/esm.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index 13cd62f51bdeb2..0b0388cd98df21 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -202,11 +202,14 @@ both Common.js and ES Modules in a single package please consult [the dual CommonJS/ES module packages section][]. **Warning**: Introducing the `"exports"` field prevents consumers of a package -from using any entry points that are not defined, including the `package.json`. -This will likely be a breaking change. To make the introduction of `"exports"` -non-breaking, ensure that every previously supported entry point is exported. -It is best to explicitly specify entry points so that the package's public API -is well-defined. For example, a project that previous exported `main`, `lib`, +from using any entry points that are not defined, including the `package.json` +(e.g. `require('your-package/package.json')`. **This will likely be a breaking +change.** + +To make the introduction of `"exports"` non-breaking, ensure that every +previously supported entry point is exported. It is best to explicitly specify +entry points so that the package’s public API is well-defined. For example, +a project that previous exported `main`, `lib`, `feature`, and the `package.json` could use the following `package.exports`: ```json From 991af5d6edf8e3e73ced5bed7082c69a4f223479 Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Mon, 4 May 2020 11:03:38 -0400 Subject: [PATCH 16/24] Update doc/api/esm.md Co-authored-by: Rob Palmer --- doc/api/esm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index 0b0388cd98df21..b3db1a4f89282e 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -193,7 +193,7 @@ precedence over `"main"`. It is important to note that `"exports"` are not specific to ES modules or CommonJS; `"main"` will be overridden by `"exports"` if it exists. As such `"main"` cannot be used as a fallback for CommonJS but it can be used as a fallback for legacy versions of Node.js that do not -support the exports field. +support the `"exports"` field. [Conditional Exports][] can be used within `"exports"` to define different package entry points per environment, including whether the package is From 33cdd0580cd8fab9f819f50e947e3ca13a395553 Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Mon, 4 May 2020 11:03:47 -0400 Subject: [PATCH 17/24] Update doc/api/esm.md Co-authored-by: Rob Palmer --- doc/api/esm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index b3db1a4f89282e..e6af3c7db8bbb7 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -198,7 +198,7 @@ support the `"exports"` field. [Conditional Exports][] can be used within `"exports"` to define different package entry points per environment, including whether the package is referenced via `require` or via `import`. For more information about supporting -both Common.js and ES Modules in a single package please consult +both CommonJS and ES Modules in a single package please consult [the dual CommonJS/ES module packages section][]. **Warning**: Introducing the `"exports"` field prevents consumers of a package From a313dbc044a8034a2f47ace37e607d4a776374aa Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Mon, 4 May 2020 11:07:16 -0400 Subject: [PATCH 18/24] fixup: remove note regarding tooling --- doc/api/esm.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index e6af3c7db8bbb7..a835bea3ffa6e4 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -227,8 +227,7 @@ a project that previous exported `main`, `lib`, As a last resort, package encapsulation can be disabled entirely by creating an export for the root of the package `"./": "./"`. This will expose every file in -the package at the cost of disabling encapsulation and the tooling and optimization -benefits that come with it. +the package at the cost of disabling encapsulation. #### Main Entry Point Export From 68a09d54420d6ae3631a1f1e742e9550d96df370 Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Mon, 4 May 2020 11:07:52 -0400 Subject: [PATCH 19/24] fixup: explicitly enumerate --- doc/api/esm.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/api/esm.md b/doc/api/esm.md index a835bea3ffa6e4..23d4827f9cc216 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -217,6 +217,7 @@ a project that previous exported `main`, `lib`, "exports": { ".": "./lib/index.js", "./lib": "./lib/index.js", + "./lib/index": "./lib/index.js", "./lib/index.js": "./lib/index.js", "./feature": "./feature/index.js", "./feature/index.js": "./feature/index.js", From 65cdd69eef3332a3a3db52526e4065a9f75c7d0f Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Mon, 4 May 2020 11:09:54 -0400 Subject: [PATCH 20/24] fixup: include folder example --- doc/api/esm.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/doc/api/esm.md b/doc/api/esm.md index 23d4827f9cc216..ee4078fd13ae68 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -226,6 +226,21 @@ a project that previous exported `main`, `lib`, } ``` +Alternatively a project could choose to export entire folders: + +```json +{ + "exports": { + ".": "./lib/index.js", + "./lib": "./lib/index.js", + "./lib/": "./lib/", + "./feature": "./feature/index.js", + "./feature/": "./feature/", + "./package.json": "./package.json" + } +} +``` + As a last resort, package encapsulation can be disabled entirely by creating an export for the root of the package `"./": "./"`. This will expose every file in the package at the cost of disabling encapsulation. From a1614cc300aa7c0fa55a2739f375770b25ed125c Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Mon, 4 May 2020 11:33:14 -0400 Subject: [PATCH 21/24] fixup: be explicit about other limitations of ./ export --- doc/api/esm.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index ee4078fd13ae68..6001b1f19e6aa6 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -214,6 +214,7 @@ a project that previous exported `main`, `lib`, ```json { + "name": "my-mod", "exports": { ".": "./lib/index.js", "./lib": "./lib/index.js", @@ -230,6 +231,7 @@ Alternatively a project could choose to export entire folders: ```json { + "name": "my-mod", "exports": { ".": "./lib/index.js", "./lib": "./lib/index.js", @@ -243,7 +245,7 @@ Alternatively a project could choose to export entire folders: As a last resort, package encapsulation can be disabled entirely by creating an export for the root of the package `"./": "./"`. This will expose every file in -the package at the cost of disabling encapsulation. +the package at the cost of disabling encapsulation. As the ES Module loader in Node.js will not resolve file extensions or an `index.js` exporting the root is less expressive than either of the above examples as individuals will be unable to `import feature from 'my-mod/feature'`. #### Main Entry Point Export From bab451c1e16430c385f74746513fe97c608b50f9 Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Mon, 4 May 2020 11:44:21 -0400 Subject: [PATCH 22/24] fixup: fix lint --- doc/api/esm.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index 6001b1f19e6aa6..d2aa446c5a4670 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -189,17 +189,17 @@ This encapsulation allows module authors to define a public interface for their package. If both `"exports"` and `"main"` are defined, the `"exports"` field takes -precedence over `"main"`. It is important to note that `"exports"` are not -specific to ES modules or CommonJS; `"main"` will be overridden by `"exports"` -if it exists. As such `"main"` cannot be used as a fallback for CommonJS -but it can be used as a fallback for legacy versions of Node.js that do not -support the `"exports"` field. +precedence over `"main"`. `"exports"` are not specific to ES modules or +CommonJS; `"main"` will be overridden by `"exports"` if it exists. As such +`"main"` cannot be used as a fallback for CommonJS but it can be used as a +fallback for legacy versions of Node.js that do not support the `"exports"` +field. [Conditional Exports][] can be used within `"exports"` to define different package entry points per environment, including whether the package is referenced via `require` or via `import`. For more information about supporting both CommonJS and ES Modules in a single package please consult -[the dual CommonJS/ES module packages section][]. +[the dual CommonJS/ES module packages section][]. **Warning**: Introducing the `"exports"` field prevents consumers of a package from using any entry points that are not defined, including the `package.json` @@ -245,7 +245,10 @@ Alternatively a project could choose to export entire folders: As a last resort, package encapsulation can be disabled entirely by creating an export for the root of the package `"./": "./"`. This will expose every file in -the package at the cost of disabling encapsulation. As the ES Module loader in Node.js will not resolve file extensions or an `index.js` exporting the root is less expressive than either of the above examples as individuals will be unable to `import feature from 'my-mod/feature'`. +the package at the cost of disabling encapsulation. As the ES Module loader in +Node.js will not resolve file extensions or an `index.js` exporting the root is +less expressive than either of the above examples as individuals will be unable +to `import feature from 'my-mod/feature'`. #### Main Entry Point Export From 4f97c02205a37b6c2dcd240fb98b810e3fa482b0 Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Tue, 5 May 2020 01:26:10 -0400 Subject: [PATCH 23/24] Update doc/api/esm.md Co-authored-by: Guy Bedford --- doc/api/esm.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index d2aa446c5a4670..1c98a8361de429 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -245,10 +245,11 @@ Alternatively a project could choose to export entire folders: As a last resort, package encapsulation can be disabled entirely by creating an export for the root of the package `"./": "./"`. This will expose every file in -the package at the cost of disabling encapsulation. As the ES Module loader in -Node.js will not resolve file extensions or an `index.js` exporting the root is -less expressive than either of the above examples as individuals will be unable -to `import feature from 'my-mod/feature'`. +the package at the cost of disabling the encapsulation and potential tooling +benefits this provides. As the ES Module loader in Node.js will not resolve file +extensions or an `index.js` exporting the root is less expressive than either of +the above examples as individuals will sill be unable to +`import feature from 'my-mod/feature'`. #### Main Entry Point Export From b15fc40909ee95dace84362b1468f0be61c96587 Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Tue, 5 May 2020 01:36:26 -0400 Subject: [PATCH 24/24] fixup: one more doc tweak --- doc/api/esm.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index 1c98a8361de429..cf50501b7e3fc1 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -246,10 +246,12 @@ Alternatively a project could choose to export entire folders: As a last resort, package encapsulation can be disabled entirely by creating an export for the root of the package `"./": "./"`. This will expose every file in the package at the cost of disabling the encapsulation and potential tooling -benefits this provides. As the ES Module loader in Node.js will not resolve file -extensions or an `index.js` exporting the root is less expressive than either of -the above examples as individuals will sill be unable to -`import feature from 'my-mod/feature'`. +benefits this provides. As the ES Module loader in Node.js enforces the use of +[the full specifier path][], exporting the root rather than being explicit +about entry is less expressive than either of the prior examples. Not only +will encapsulation be lost but module consumers will be unable to +`import feature from 'my-mod/feature'` as they will need to provide the full +path `import feature from 'my-mod/feature/index.js`. #### Main Entry Point Export @@ -1801,6 +1803,7 @@ success! [dynamic instantiate hook]: #esm_code_dynamicinstantiate_code_hook [import an ES or CommonJS module for its side effects only]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#Import_a_module_for_its_side_effects_only [special scheme]: https://url.spec.whatwg.org/#special-scheme +[the full specifier path]: #esm_mandatory_file_extensions [the official standard format]: https://tc39.github.io/ecma262/#sec-modules [the dual CommonJS/ES module packages section]: #esm_dual_commonjs_es_module_packages [transpiler loader example]: #esm_transpiler_loader