From 37f9d4800411650d801af082484b6f323285e07b Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Sat, 9 Jan 2021 13:58:14 -0500 Subject: [PATCH 1/9] doc: define "browser", "production", "development" conditions --- doc/api/packages.md | 49 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 43 insertions(+), 6 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index 4a7fea3b5635ef..6c6507bb1833e4 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -449,7 +449,7 @@ For example, a package that wants to provide different ES module exports for } ``` -Node.js supports the following conditions out of the box: +Node.js implements the following conditions: * `"import"` - matches when the package is loaded via `import` or `import()`, or via any top-level import or resolve operation by the @@ -472,11 +472,6 @@ matching, earlier entries have higher priority and take precedence over later entries. _The general rule is that conditions should be from most specific to least specific in object order_. -Other conditions such as `"browser"`, `"electron"`, `"deno"`, `"react-native"`, -etc., are unknown to Node.js, and thus ignored. Runtimes or tools other than -Node.js can use them at their discretion. Further restrictions, definitions, or -guidance on condition names might occur in the future. - Using the `"import"` and `"require"` conditions can lead to some hazards, which are further explained in [the dual CommonJS/ES module packages section][]. @@ -547,6 +542,47 @@ exports, while resolving the existing `"node"`, `"default"`, `"import"`, and Any number of custom conditions can be set with repeat flags. +### Conditions Definitions + +The `"import"`, `"require"`, `"node"` and `"default"` conditions are defined +and implemented in Node.js core, [as specified above](#conditional_exports). + +The following condition definitions are currently endorsed by Node.js: + +* `"browser"` - any environment which implements a standard subset of + global browser APIs available from JS in web browsers, including the DOM + APIs. +* `"development"` - can be used to define a development-only environment + entry point. Enabled via the `--conditions=development` flag to Node.js. + _Must always be mutually exclusive with `"production"`._ +* `"production"` - can be used to define a production environment entry + point. Enabled via the `--conditions=production` flag to Node.js. + _Must always be mutually exclusive with `"development"`._ + +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. + +Platform specific conditions such as `"deno"`, `"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 creation a PR to the +[Node.js documentation for this section][]. The requirements for listing a +new condition definition here are that: + +* The definition should be clear and unambigious for all implementers. +* The use case for why the condition is needed should be clearly justified. +* There should exist sufficient existing implementation usage. +* The condition name should not conflict with another condition definition or + condition in wide usage. +* The listing of the condition definition should provide a coordination + benefit to the ecosystem that wouldn't otherwise be possible. For example, + this would not necessarily be the case for company-specific or + application-specific conditions. + +The above definitions may be moved to a dedicated conditions registry in due +course. + ### Self-referencing a package using its name Within a package, the values defined in the package’s @@ -1056,6 +1092,7 @@ This field defines [subpath imports][] for the current package. [CommonJS]: modules.md [ES module]: esm.md [ES modules]: esm.md +[Node.js documentation for this section]: https://github.com/nodejs/node/blob/master/doc/api/packages.md#conditions-definitions [`ERR_PACKAGE_PATH_NOT_EXPORTED`]: errors.md#errors_err_package_path_not_exported [`esm`]: https://github.com/standard-things/esm#readme [`"exports"`]: #packages_exports From cfface9834b543676d413fd6b45fe65157dc0659 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Sat, 9 Jan 2021 14:08:42 -0500 Subject: [PATCH 2/9] fixup --- 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 6c6507bb1833e4..5f651bba5ad8a0 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -558,7 +558,7 @@ The following condition definitions are currently endorsed by Node.js: * `"production"` - can be used to define a production environment entry point. Enabled via the `--conditions=production` flag to Node.js. _Must always be mutually exclusive with `"development"`._ - + 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. @@ -566,7 +566,7 @@ Platform specific conditions such as `"deno"`, `"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 creation a PR to the +New conditions definitions may be added to this list by creating a PR to the [Node.js documentation for this section][]. The requirements for listing a new condition definition here are that: From 733a8c026a7b021335114f975a100fd39d989b32 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Sat, 9 Jan 2021 11:09:54 -0800 Subject: [PATCH 3/9] Update doc/api/packages.md 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 5f651bba5ad8a0..24a9c519c1f21d 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -562,7 +562,7 @@ The following condition definitions are currently endorsed by Node.js: 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. -Platform specific conditions such as `"deno"`, `"electron"` or `"react-native"` +Platform specific conditions such as `"deno"`, `"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 37af0e633be3da568cdf5d24f7c9a8f1457bd3fc Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Sat, 9 Jan 2021 14:16:37 -0500 Subject: [PATCH 4/9] fixup --- doc/api/packages.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index 24a9c519c1f21d..57ffaacdc1da2a 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -545,7 +545,8 @@ Any number of custom conditions can be set with repeat flags. ### Conditions Definitions The `"import"`, `"require"`, `"node"` and `"default"` conditions are defined -and implemented in Node.js core, [as specified above](#conditional_exports). +and implemented in Node.js core, +[as specified above](#esm_conditional_exports). The following condition definitions are currently endorsed by Node.js: From 502986c2935e5ce7456eb91cbadfbeb501dafeda Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Sun, 10 Jan 2021 11:43:32 -0500 Subject: [PATCH 5/9] update --conditions flag notes --- doc/api/packages.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index 57ffaacdc1da2a..3cf0ec3e4ca315 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -554,11 +554,12 @@ The following condition definitions are currently endorsed by Node.js: global browser APIs available from JS in web browsers, including the DOM APIs. * `"development"` - can be used to define a development-only environment - entry point. Enabled via the `--conditions=development` flag to Node.js. - _Must always be mutually exclusive with `"production"`._ + entry point. _Must always be mutually exclusive with `"production"`._ * `"production"` - can be used to define a production environment entry - point. Enabled via the `--conditions=production` flag to Node.js. - _Must always be mutually exclusive with `"development"`._ + point. _Must always be mutually exclusive with `"development"`._ + +The above user conditions can be enabled in Node.js via the [`--conditions` +flag](#packages_resolving_user_conditions). 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. From 097739056505bb2953c84a1bc45bf7119a5ffbc2 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Mon, 11 Jan 2021 12:14:56 -0500 Subject: [PATCH 6/9] move custom conditions note to cover whole section --- doc/api/packages.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/api/packages.md b/doc/api/packages.md index 3cf0ec3e4ca315..b9ed112a8f1e9d 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -548,6 +548,9 @@ The `"import"`, `"require"`, `"node"` and `"default"` conditions are defined and implemented in Node.js core, [as specified above](#esm_conditional_exports). +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. + The following condition definitions are currently endorsed by Node.js: * `"browser"` - any environment which implements a standard subset of @@ -561,9 +564,6 @@ The following condition definitions are currently endorsed by Node.js: The above user conditions can be enabled in Node.js via the [`--conditions` flag](#packages_resolving_user_conditions). -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. - Platform specific conditions such as `"deno"`, `"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 678ad6d629f03179bf091d0e04b86cea90348b91 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Mon, 11 Jan 2021 17:40:51 -0500 Subject: [PATCH 7/9] move `--conditions` flag note --- doc/api/packages.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/api/packages.md b/doc/api/packages.md index b9ed112a8f1e9d..79b63fef8bf0ad 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -551,6 +551,9 @@ and implemented in Node.js core, 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](#packages_resolving_user_conditions). + The following condition definitions are currently endorsed by Node.js: * `"browser"` - any environment which implements a standard subset of From 6717f7407deffce576901d99139acd1cce3cf758 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Mon, 11 Jan 2021 17:41:14 -0500 Subject: [PATCH 8/9] Update doc/api/packages.md 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 79b63fef8bf0ad..0b15e137ec19aa 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -557,7 +557,7 @@ flag](#packages_resolving_user_conditions). The following condition definitions are currently endorsed by Node.js: * `"browser"` - any environment which implements a standard subset of - global browser APIs available from JS in web browsers, including the DOM + global browser APIs available from JavaScript in web browsers, including the DOM APIs. * `"development"` - can be used to define a development-only environment entry point. _Must always be mutually exclusive with `"production"`._ From 47f941cec62df987f15dbc523530dfe1f0e1b2f5 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Mon, 11 Jan 2021 17:42:51 -0500 Subject: [PATCH 9/9] lint fix --- 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 0b15e137ec19aa..645d7a4b82459c 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -556,8 +556,8 @@ flag](#packages_resolving_user_conditions). 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 +* `"browser"` - any environment which implements a standard subset of global + browser APIs available from JavaScript in web browsers, including the DOM APIs. * `"development"` - can be used to define a development-only environment entry point. _Must always be mutually exclusive with `"production"`._