From 8b3bf213323de2283226b718f4c53b8678cbc306 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Tue, 2 Nov 2021 21:41:41 -0700 Subject: [PATCH 01/15] doc: endorse "source" and "deno" conditions --- doc/api/packages.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index 94b4a1e1057ad5..4e85b3bbdfb054 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -612,16 +612,19 @@ The following condition definitions are currently endorsed by Node.js: * `"browser"` - any environment which implements a standard subset of global browser APIs available from JavaScript in web browsers, including the DOM APIs. +* `"deno"` - indicates a variation for the Deno platform. * `"development"` - can be used to define a development-only environment entry point. _Must always be mutually exclusive with `"production"`._ * `"production"` - can be used to define a production environment entry point. _Must always be mutually exclusive with `"development"`._ +* `"source"` - indicates the original .js source file without minification + or bundling optimizations, useful for development and debugging workflows. The above user conditions can be enabled in Node.js via the [`--conditions` flag][]. -Platform specific conditions such as `"deno"`, `"electron"`, or `"react-native"` -may be used, but while there remain no implementation or integration intent +Platform specific conditions such as `"electron"`, or `"react-native"` may +be used, but while there remain no implementation or integration intent from these platforms, the above are not explicitly endorsed by Node.js. New conditions definitions may be added to this list by creating a pull request From de4eab63b070e0804d42910aa30460f1bcf160fe Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Tue, 2 Nov 2021 21:56:17 -0700 Subject: [PATCH 02/15] fixup: add "types" as well --- doc/api/packages.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/api/packages.md b/doc/api/packages.md index 4e85b3bbdfb054..1cfaec1070ccd8 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -619,6 +619,9 @@ The following condition definitions are currently endorsed by Node.js: point. _Must always be mutually exclusive with `"development"`._ * `"source"` - indicates the original .js source file without minification or bundling optimizations, useful for development and debugging workflows. +* `"types"` - can be used by typing systems to resolve the typing file for + the given export, possible since the interface should be the same for all + variations. The above user conditions can be enabled in Node.js via the [`--conditions` flag][]. From 31071a50daf95a973ab182248651e55dced2c1d6 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Tue, 2 Nov 2021 22:20:31 -0700 Subject: [PATCH 03/15] fixup: style Co-authored-by: Rich Trott --- doc/api/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index 1cfaec1070ccd8..c54f42ac843f0d 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -628,7 +628,7 @@ The above user conditions can be enabled in Node.js via the Platform specific conditions such as `"electron"`, or `"react-native"` may be used, but while there remain no implementation or integration intent -from these platforms, the above are not explicitly endorsed by Node.js. +from these platforms, we do not yet explicitly recommend them. New conditions definitions may be added to this list by creating a pull request to the [Node.js documentation for this section][]. The requirements for listing From 949bb7cafdaf9aa9ddf1c872f32f669e60111732 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Wed, 3 Nov 2021 22:21:16 +0200 Subject: [PATCH 04/15] remove "source", clarify "development" --- doc/api/packages.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index c54f42ac843f0d..fa4973b661efa3 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -614,14 +614,14 @@ The following condition definitions are currently endorsed by Node.js: APIs. * `"deno"` - indicates a variation for the Deno platform. * `"development"` - can be used to define a development-only environment - entry point. _Must always be mutually exclusive with `"production"`._ + entry point, for example to provide additional debugging context such as + better error message when running in a development mode. _Must always be + mutually exclusive with `"production"`._ * `"production"` - can be used to define a production environment entry point. _Must always be mutually exclusive with `"development"`._ -* `"source"` - indicates the original .js source file without minification - or bundling optimizations, useful for development and debugging workflows. * `"types"` - can be used by typing systems to resolve the typing file for the given export, possible since the interface should be the same for all - variations. + variations. _This condition should always be included first._ The above user conditions can be enabled in Node.js via the [`--conditions` flag][]. From d943a226a652628360b7d44c1525cdd4d7c199ab Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Wed, 3 Nov 2021 23:06:32 +0200 Subject: [PATCH 05/15] reorder conditions in specificity ordering, note --- doc/api/packages.md | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index fa4973b661efa3..cd93ed4e125060 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -486,8 +486,17 @@ For example, a package that wants to provide different ES module exports for } ``` -Node.js implements the following conditions: +Node.js implements the following conditions, listed in order from most +specific to least specific as conditions should be defined: +* `"node-addons"` - similar to `"node"` and matches for any Node.js environment. + This condition can be used to provide an entry point which uses native C++ + addons as opposed to an entry point which is more universal and doesn't rely + on native addons. This condition can be disabled via the + [`--no-addons` flag][]. +* `"node"` - matches for any Node.js environment. Can be a CommonJS or ES + module file. _This condition should always come after `"import"` or + `"require"`._ * `"import"` - matches when the package is loaded via `import` or `import()`, or via any top-level import or resolve operation by the ECMAScript module loader. Applies regardless of the module format of the @@ -498,14 +507,6 @@ Node.js implements the following conditions: formats include CommonJS, JSON, and native addons but not ES modules as `require()` doesn't support them. _Always mutually exclusive with `"import"`._ -* `"node"` - matches for any Node.js environment. Can be a CommonJS or ES - module file. _This condition should always come after `"import"` or - `"require"`._ -* `"node-addons"` - similar to `"node"` and matches for any Node.js environment. - This condition can be used to provide an entry point which uses native C++ - addons as opposed to an entry point which is more universal and doesn't rely - on native addons. This condition can be disabled via the - [`--no-addons` flag][]. * `"default"` - the generic fallback that always matches. Can be a CommonJS or ES module file. _This condition should always come last._ @@ -607,21 +608,23 @@ Runtimes or tools other than Node.js can use them at their discretion. These user conditions can be enabled in Node.js via the [`--conditions` flag][]. -The following condition definitions are currently endorsed by Node.js: +The following condition definitions are currently endorsed by Node.js, and +are _listed in order from most to least specific, as conditions should be +used._ +* `"types"` - can be used by typing systems to resolve the typing file for + the given export, possible since the interface should be the same for all + variations. _This condition should always be included first._ +* `"deno"` - indicates a variation for the Deno platform. * `"browser"` - any environment which implements a standard subset of global browser APIs available from JavaScript in web browsers, including the DOM APIs. -* `"deno"` - indicates a variation for the Deno platform. * `"development"` - can be used to define a development-only environment entry point, for example to provide additional debugging context such as better error message when running in a development mode. _Must always be mutually exclusive with `"production"`._ * `"production"` - can be used to define a production environment entry point. _Must always be mutually exclusive with `"development"`._ -* `"types"` - can be used by typing systems to resolve the typing file for - the given export, possible since the interface should be the same for all - variations. _This condition should always be included first._ The above user conditions can be enabled in Node.js via the [`--conditions` flag][]. From 804dd2a541703adcc3c4b0587763c62c619efbf9 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Wed, 3 Nov 2021 20:14:33 -0700 Subject: [PATCH 06/15] fixup: clarify Node.js condition, remove restriction wording --- doc/api/packages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index cd93ed4e125060..a0401497952918 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -495,8 +495,8 @@ specific to least specific as conditions should be defined: on native addons. This condition can be disabled via the [`--no-addons` flag][]. * `"node"` - matches for any Node.js environment. Can be a CommonJS or ES - module file. _This condition should always come after `"import"` or - `"require"`._ + module file. _In most cases explictily calling out the Node.js platform is + not necessary._ * `"import"` - matches when the package is loaded via `import` or `import()`, or via any top-level import or resolve operation by the ECMAScript module loader. Applies regardless of the module format of the From 5791560c4220ce4df0af6c888e253325675011db Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Wed, 3 Nov 2021 23:52:21 -0700 Subject: [PATCH 07/15] clarify browser condition --- doc/api/packages.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index a0401497952918..d0fdcf6e8011fb 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -616,9 +616,7 @@ used._ the given export, possible since the interface should be the same for all variations. _This condition should always be included first._ * `"deno"` - indicates a variation for the Deno platform. -* `"browser"` - any environment which implements a standard subset of global - browser APIs available from JavaScript in web browsers, including the DOM - APIs. +* `"browser"` - any web browser environment. * `"development"` - can be used to define a development-only environment entry point, for example to provide additional debugging context such as better error message when running in a development mode. _Must always be From 22eceb1a9dc85acf547fe21df57fd493500abd25 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Fri, 5 Nov 2021 02:13:15 +0200 Subject: [PATCH 08/15] fixup: review typo Co-authored-by: Jordan Harband --- doc/api/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index d0fdcf6e8011fb..8331151aad0592 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -495,7 +495,7 @@ specific to least specific as conditions should be defined: on native addons. This condition can be disabled via the [`--no-addons` flag][]. * `"node"` - matches for any Node.js environment. Can be a CommonJS or ES - module file. _In most cases explictily calling out the Node.js platform is + module file. _In most cases explictly calling out the Node.js platform is not necessary._ * `"import"` - matches when the package is loaded via `import` or `import()`, or via any top-level import or resolve operation by the From 599f4eb8fd3d5f307cd789a42ae15f76da910616 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Thu, 4 Nov 2021 17:15:27 -0700 Subject: [PATCH 09/15] fixup: typo v2 --- doc/api/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index 8331151aad0592..5b93821860fa68 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -495,7 +495,7 @@ specific to least specific as conditions should be defined: on native addons. This condition can be disabled via the [`--no-addons` flag][]. * `"node"` - matches for any Node.js environment. Can be a CommonJS or ES - module file. _In most cases explictly calling out the Node.js platform is + module file. _In most cases explicitly calling out the Node.js platform is not necessary._ * `"import"` - matches when the package is loaded via `import` or `import()`, or via any top-level import or resolve operation by the From 502ae3c037d8ca3d12fc75ee1f01870b36e428a2 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Mon, 8 Nov 2021 03:05:00 +0200 Subject: [PATCH 10/15] fixup: code review Co-authored-by: Geoffrey Booth <456802+GeoffreyBooth@users.noreply.github.com> --- doc/api/packages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index 5b93821860fa68..eff69de763d42f 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -619,7 +619,7 @@ used._ * `"browser"` - any web browser environment. * `"development"` - can be used to define a development-only environment entry point, for example to provide additional debugging context such as - better error message when running in a development mode. _Must always be + better error messages when running in a development mode. _Must always be mutually exclusive with `"production"`._ * `"production"` - can be used to define a production environment entry point. _Must always be mutually exclusive with `"development"`._ @@ -627,7 +627,7 @@ used._ The above user conditions can be enabled in Node.js via the [`--conditions` flag][]. -Platform specific conditions such as `"electron"`, or `"react-native"` may +Platform-specific conditions such as `"electron"`, or `"react-native"` may be used, but while there remain no implementation or integration intent from these platforms, we do not yet explicitly recommend them. From 1a83be25ce4f5d91182aa632b5ed59c28c1e6817 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Mon, 8 Nov 2021 11:19:26 +0200 Subject: [PATCH 11/15] fixup: code review Co-authored-by: Geoffrey Booth <456802+GeoffreyBooth@users.noreply.github.com> --- doc/api/packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index eff69de763d42f..31e1a4d94bf6cb 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -629,7 +629,7 @@ The above user conditions can be enabled in Node.js via the Platform-specific conditions such as `"electron"`, or `"react-native"` may be used, but while there remain no implementation or integration intent -from these platforms, we do not yet explicitly recommend them. +from these platforms, they are not currently explicitly recommended. New conditions definitions may be added to this list by creating a pull request to the [Node.js documentation for this section][]. The requirements for listing From bf8c70223c6fea7a411316d0bb71f79e005ea149 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Wed, 17 Nov 2021 15:34:25 +0200 Subject: [PATCH 12/15] update description of conditions definitions --- doc/api/packages.md | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index 31e1a4d94bf6cb..bb28c04939ce46 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -518,6 +518,12 @@ least specific in object order_. Using the `"import"` and `"require"` conditions can lead to some hazards, which are further explained in [the dual CommonJS/ES module packages section][]. +The `"node-addons"` condition can be used to provide an entry point which +uses native C++ addons. However, this condition can be disabled via the +[`--no-addons` flag][]. When using `"node-addons"`, it's recommended to treat +`"default"` as an enhancement that provides a more universal entry point, e.g. +using WebAssembly instead of a native addon. + Conditional exports can also be extended to exports subpaths, for example: ```json @@ -597,20 +603,14 @@ The `"import"`, `"require"`, `"node"`, `"node-addons"` and `"default"` conditions are defined and implemented in Node.js core, [as specified above](#conditional-exports). -The `"node-addons"` condition can be used to provide an entry point which -uses native C++ addons. However, this condition can be disabled via the -[`--no-addons` flag][]. When using `"node-addons"`, it's recommended to treat -`"default"` as an enhancement that provides a more universal entry point, e.g. -using WebAssembly instead of a native addon. - Other condition strings are unknown to Node.js and thus ignored by default. Runtimes or tools other than Node.js can use them at their discretion. These user conditions can be enabled in Node.js via the [`--conditions` flag][]. -The following condition definitions are currently endorsed by Node.js, and -are _listed in order from most to least specific, as conditions should be -used._ +Since user package conditions require clear definitions to ensure correct usage, +a list of common known package conditions and their strict definitions is provided +below to assist with ecosystem coordination. * `"types"` - can be used by typing systems to resolve the typing file for the given export, possible since the interface should be the same for all @@ -627,10 +627,6 @@ used._ The above user conditions can be enabled in Node.js via the [`--conditions` flag][]. -Platform-specific conditions such as `"electron"`, or `"react-native"` may -be used, but while there remain no implementation or integration intent -from these platforms, they are not currently explicitly recommended. - New conditions definitions may be added to this list by creating a pull request to the [Node.js documentation for this section][]. The requirements for listing a new condition definition here are that: From 438c1797ed6974b48ffe22fe0c8c02bd36a4a416 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Wed, 17 Nov 2021 16:10:15 +0200 Subject: [PATCH 13/15] rename title, further rewording --- doc/api/packages.md | 25 ++++++++++--------------- 1 file changed, 10 insertions(+), 15 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index bb28c04939ce46..37896bfbe2ce05 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -597,20 +597,18 @@ exports, while resolving the existing `"node"`, `"node-addons"`, `"default"`, Any number of custom conditions can be set with repeat flags. -### Conditions Definitions +### Community Conditions Definitions -The `"import"`, `"require"`, `"node"`, `"node-addons"` and `"default"` -conditions are defined and implemented in Node.js core, -[as specified above](#conditional-exports). +Conditions strings other than the `"import"`, `"require"`, `"node"`, +`"node-addons"` and `"default"` conditions [implemented in Node.js core] +(#conditional-exports) are ignored by default. -Other condition strings are unknown to Node.js and thus ignored by default. -Runtimes or tools other than Node.js can use them at their discretion. +Other platforms may implement other conditions and user conditions can be enabled +in Node.js via the [`--conditions` / `-C` flag][]. -These user conditions can be enabled in Node.js via the [`--conditions` flag][]. - -Since user package conditions require clear definitions to ensure correct usage, -a list of common known package conditions and their strict definitions is provided -below to assist with ecosystem coordination. +Since custom package conditions require clear definitions to ensure correct usage, +a list of common known package conditions and their strict definitions is +provided below to assist with ecosystem coordination. * `"types"` - can be used by typing systems to resolve the typing file for the given export, possible since the interface should be the same for all @@ -624,9 +622,6 @@ below to assist with ecosystem coordination. * `"production"` - can be used to define a production environment entry point. _Must always be mutually exclusive with `"development"`._ -The above user conditions can be enabled in Node.js via the -[`--conditions` flag][]. - New conditions definitions may be added to this list by creating a pull request to the [Node.js documentation for this section][]. The requirements for listing a new condition definition here are that: @@ -1236,7 +1231,7 @@ This field defines [subpath imports][] for the current package. [`"name"`]: #name [`"packageManager"`]: #packagemanager [`"type"`]: #type -[`--conditions` flag]: #resolving-user-conditions +[`--conditions` / `-C` flag]: #resolving-user-conditions [`--no-addons` flag]: cli.md#--no-addons [`ERR_PACKAGE_PATH_NOT_EXPORTED`]: errors.md#err_package_path_not_exported [`esm`]: https://github.com/standard-things/esm#readme From eb9f27e8576c2b0e835c7172687a13b87fafd42c Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Wed, 17 Nov 2021 09:55:24 -0800 Subject: [PATCH 14/15] linting fixes --- doc/api/packages.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index 37896bfbe2ce05..b2fdb92a3c160e 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -599,16 +599,16 @@ Any number of custom conditions can be set with repeat flags. ### Community Conditions Definitions -Conditions strings other than the `"import"`, `"require"`, `"node"`, -`"node-addons"` and `"default"` conditions [implemented in Node.js core] -(#conditional-exports) are ignored by default. +Condition strings other than the `"import"`, `"require"`, `"node"`, +`"node-addons"` and `"default"` conditions +[implemented in Node.js core](#conditional-exports) are ignored by default. -Other platforms may implement other conditions and user conditions can be enabled -in Node.js via the [`--conditions` / `-C` flag][]. +Other platforms may implement other conditions and user conditions can be +enabled in Node.js via the [`--conditions` / `-C` flag][]. -Since custom package conditions require clear definitions to ensure correct usage, -a list of common known package conditions and their strict definitions is -provided below to assist with ecosystem coordination. +Since custom package conditions require clear definitions to ensure correct +usage, a list of common known package conditions and their strict definitions +is provided below to assist with ecosystem coordination. * `"types"` - can be used by typing systems to resolve the typing file for the given export, possible since the interface should be the same for all From 7cefba2f67d313a63173d76adf4c15b9fd00f0e6 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Wed, 17 Nov 2021 10:15:04 -0800 Subject: [PATCH 15/15] remove singular types note --- doc/api/packages.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index b2fdb92a3c160e..ad487ce30b0967 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -611,8 +611,7 @@ usage, a list of common known package conditions and their strict definitions is provided below to assist with ecosystem coordination. * `"types"` - can be used by typing systems to resolve the typing file for - the given export, possible since the interface should be the same for all - variations. _This condition should always be included first._ + the given export. _This condition should always be included first._ * `"deno"` - indicates a variation for the Deno platform. * `"browser"` - any web browser environment. * `"development"` - can be used to define a development-only environment