@@ -407,7 +407,7 @@ For example, a package that wants to provide different ES module exports for |
407 | 407 | } |
408 | 408 | ``` |
409 | 409 |
|
410 | | -Node.js supports the following conditions out of the box: |
| 410 | +Node.js implements the following conditions: |
411 | 411 |
|
412 | 412 | * `"import"` - matches when the package is loaded via `import` or |
413 | 413 | `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 |
430 | 430 | entries. _The general rule is that conditions should be from most specific to |
431 | 431 | least specific in object order_. |
432 | 432 |
|
433 | | -Other conditions such as `"browser"`, `"electron"`, `"deno"`, `"react-native"`, |
434 | | -etc., are unknown to Node.js, and thus ignored. Runtimes or tools other than |
435 | | -Node.js can use them at their discretion. Further restrictions, definitions, or |
436 | | -guidance on condition names might occur in the future. |
437 | | - |
438 | 433 | Using the `"import"` and `"require"` conditions can lead to some hazards, |
439 | 434 | which are further explained in [the dual CommonJS/ES module packages section][]. |
440 | 435 |
|
@@ -505,6 +500,52 @@ exports, while resolving the existing `"node"`, `"default"`, `"import"`, and |
505 | 500 |
|
506 | 501 | Any number of custom conditions can be set with repeat flags. |
507 | 502 |
|
| 503 | +### Conditions Definitions |
| 504 | + |
| 505 | +The `"import"`, `"require"`, `"node"` and `"default"` conditions are defined |
| 506 | +and implemented in Node.js core, |
| 507 | +[as specified above](#esm_conditional_exports). |
| 508 | + |
| 509 | +Other condition strings are unknown to Node.js and thus ignored by default. |
| 510 | +Runtimes or tools other than Node.js can use them at their discretion. |
| 511 | + |
| 512 | +These user conditions can be enabled in Node.js via the [`--conditions` |
| 513 | +flag](#packages_resolving_user_conditions). |
| 514 | + |
| 515 | +The following condition definitions are currently endorsed by Node.js: |
| 516 | + |
| 517 | +* `"browser"` - any environment which implements a standard subset of global |
| 518 | + browser APIs available from JavaScript in web browsers, including the DOM |
| 519 | + APIs. |
| 520 | +* `"development"` - can be used to define a development-only environment |
| 521 | + entry point. _Must always be mutually exclusive with `"production"`._ |
| 522 | +* `"production"` - can be used to define a production environment entry |
| 523 | + point. _Must always be mutually exclusive with `"development"`._ |
| 524 | + |
| 525 | +The above user conditions can be enabled in Node.js via the [`--conditions` |
| 526 | +flag](#packages_resolving_user_conditions). |
| 527 | + |
| 528 | +Platform specific conditions such as `"deno"`, `"electron"`, or `"react-native"` |
| 529 | +may be used, but while there remain no implementation or integration intent |
| 530 | +from these platforms, the above are not explicitly endorsed by Node.js. |
| 531 | + |
| 532 | +New conditions definitions may be added to this list by creating a PR to the |
| 533 | +[Node.js documentation for this section][]. The requirements for listing a |
| 534 | +new condition definition here are that: |
| 535 | + |
| 536 | +* The definition should be clear and unambigious for all implementers. |
| 537 | +* The use case for why the condition is needed should be clearly justified. |
| 538 | +* There should exist sufficient existing implementation usage. |
| 539 | +* The condition name should not conflict with another condition definition or |
| 540 | + condition in wide usage. |
| 541 | +* The listing of the condition definition should provide a coordination |
| 542 | + benefit to the ecosystem that wouldn't otherwise be possible. For example, |
| 543 | + this would not necessarily be the case for company-specific or |
| 544 | + application-specific conditions. |
| 545 | + |
| 546 | +The above definitions may be moved to a dedicated conditions registry in due |
| 547 | +course. |
| 548 | + |
508 | 549 | ### Self-referencing a package using its name |
509 | 550 |
|
510 | 551 | Within a package, the values defined in the package’s |
@@ -1014,6 +1055,7 @@ This field defines [subpath imports][] for the current package. |
1014 | 1055 | [CommonJS]: modules.md |
1015 | 1056 | [ES module]: esm.md |
1016 | 1057 | [ES modules]: esm.md |
| 1058 | +[Node.js documentation for this section]: https://github.com/nodejs/node/blob/master/doc/api/packages.md#conditions-definitions |
1017 | 1059 | [`ERR_PACKAGE_PATH_NOT_EXPORTED`]: errors.md#errors_err_package_path_not_exported |
1018 | 1060 | [`esm`]: https://github.com/standard-things/esm#readme |
1019 | 1061 | [`"exports"`]: #packages_exports |
|