diff options
author | Derek Lewis <DerekNonGeneric@inf.is> | 2020-06-15 02:30:38 +0300 |
---|---|---|
committer | James M Snell <jasnell@gmail.com> | 2020-07-03 22:16:23 +0300 |
commit | db3b209e7df254794873be5ac91345dee034e130 (patch) | |
tree | ef990c88042a95a084c6c963c942518220a25b37 /doc/api/esm.md | |
parent | a7c6806adc5591ba782cb7c520fb983bc0e25ec1 (diff) |
doc: clarify esm conditional exports prose
This commit clarifies the behavior of a couple aspects of
conditional exports that may have been difficult to grasp
from the prose alone.
PR-URL: https://github.com/nodejs/node/pull/33886
Reviewed-By: Guy Bedford <guybedford@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
Diffstat (limited to 'doc/api/esm.md')
-rw-r--r-- | doc/api/esm.md | 27 |
1 files changed, 14 insertions, 13 deletions
diff --git a/doc/api/esm.md b/doc/api/esm.md index 06a9f89ee57..c06ba4782af 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -419,7 +419,7 @@ For example, a package that wants to provide different ES module exports for } ``` -Node.js supports the following conditions: +Node.js supports the following conditions out of the box: * `"import"` - matched when the package is loaded via `import` or `import()`. Can reference either an ES module or CommonJS file, as both @@ -434,18 +434,18 @@ Node.js supports the following conditions: * `"default"` - the generic fallback that will always match. Can be a CommonJS or ES module file. _This condition should always come last._ -Condition matching is applied in object order from first to last within the -`"exports"` object. _The general rule is that conditions should be used -from most specific to least specific in object order._ +Within the `"exports"` object, key order is significant. During condition +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 ignored by Node.js but may be used by other runtimes or tools. -Further restrictions, definitions or guidance on condition names may be -provided in the future. +etc. are unknown to, and thus ignored by Node.js. Runtimes or tools other than +Node.js may use them at their discretion. Further restrictions, definitions, or +guidance on condition names may occur in the future. Using the `"import"` and `"require"` conditions can lead to some hazards, -which are explained further in -[the dual CommonJS/ES module packages section][]. +which are further explained in [the dual CommonJS/ES module packages section][]. Conditional exports can also be extended to exports subpaths, for example: @@ -1154,10 +1154,11 @@ The `conditions` property on the `context` is an array of conditions for for looking up conditional mappings elsewhere or to modify the list when calling the default resolution logic. -The [current set of Node.js default conditions][Conditional exports] will always -be in the `context.conditions` list passed to the hook. If the hook wants to -ensure Node.js-compatible resolution logic, all items from this default -condition list **must** be passed through to the `defaultResolve` function. +The current [package exports conditions][Conditional Exports] will always be in +the `context.conditions` array passed into the hook. To guarantee _default +Node.js module specifier resolution behavior_ when calling `defaultResolve`, the +`context.conditions` array passed to it _must_ include _all_ elements of the +`context.conditions` array originally passed into the `resolve` hook. ```js /** |