diff options
author | Guy Bedford <guybedford@gmail.com> | 2021-01-09 21:58:14 +0300 |
---|---|---|
committer | Michaël Zasso <targos@protonmail.com> | 2021-05-01 13:24:53 +0300 |
commit | 7fbbdb831a764ea941b9ea916b6c40e7de384a8b (patch) | |
tree | 6c7129621d3c354121441ee6d57d76ec6eb15ff6 /doc/api/packages.md | |
parent | 5c74dc7227630fca65b1183cfe33e13ebbac23b4 (diff) |
doc: define "browser", "production", "development"
Defines the above exports conditions by convention
as well as some guidance for further conditions
definitions in future
PR-URL: https://github.com/nodejs/node/pull/36856
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com>
Diffstat (limited to 'doc/api/packages.md')
-rw-r--r-- | doc/api/packages.md | 54 |
1 files changed, 48 insertions, 6 deletions
diff --git a/doc/api/packages.md b/doc/api/packages.md index 315a341a368..fbae6319b72 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -407,7 +407,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 @@ -430,11 +430,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][]. @@ -505,6 +500,52 @@ 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](#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. + +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 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"`._ +* `"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](#packages_resolving_user_conditions). + +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 creating 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 @@ -1014,6 +1055,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 |