Skip to content

Commit

Permalink
doc: define "types", "deno" community conditions
Browse files Browse the repository at this point in the history
PR-URL: #40708
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
  • Loading branch information
guybedford authored and danielleadams committed Feb 1, 2022
1 parent 4ffbff2 commit dead21c
Showing 1 changed file with 33 additions and 36 deletions.
69 changes: 33 additions & 36 deletions doc/api/packages.md
Original file line number Diff line number Diff line change
Expand Up @@ -531,8 +531,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. _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
ECMAScript module loader. Applies regardless of the module format of the
Expand All @@ -543,14 +552,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._

Expand All @@ -562,6 +563,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
Expand Down Expand Up @@ -635,40 +642,30 @@ 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).
Condition strings other than the `"import"`, `"require"`, `"node"`,
`"node-addons"` and `"default"` conditions
[implemented in Node.js core](#conditional-exports) are ignored by default.

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.
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 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.

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.
* `"types"` - can be used by typing systems to resolve the typing file for
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
entry point. _Must always be mutually exclusive with `"production"`._
entry point, for example to provide additional debugging context such as
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"`._

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
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
to the [Node.js documentation for this section][]. The requirements for listing
a new condition definition here are that:
Expand Down Expand Up @@ -1278,7 +1275,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
Expand Down

0 comments on commit dead21c

Please sign in to comment.