Skip to content

Commit 8fb265d

Browse files
Derek Lewisaddaleax
Derek Lewis
authored andcommitted
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: #33886 Reviewed-By: Guy Bedford <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: James M Snell <[email protected]>
1 parent 49383c8 commit 8fb265d

File tree

1 file changed

+14
-13
lines changed

1 file changed

+14
-13
lines changed

doc/api/esm.md

+14-13
Original file line numberDiff line numberDiff line change
@@ -419,7 +419,7 @@ For example, a package that wants to provide different ES module exports for
419419
}
420420
```
421421

422-
Node.js supports the following conditions:
422+
Node.js supports the following conditions out of the box:
423423

424424
* `"import"` - matched when the package is loaded via `import` or
425425
`import()`. Can reference either an ES module or CommonJS file, as both
@@ -434,18 +434,18 @@ Node.js supports the following conditions:
434434
* `"default"` - the generic fallback that will always match. Can be a CommonJS
435435
or ES module file. _This condition should always come last._
436436

437-
Condition matching is applied in object order from first to last within the
438-
`"exports"` object. _The general rule is that conditions should be used
439-
from most specific to least specific in object order._
437+
Within the `"exports"` object, key order is significant. During condition
438+
matching, earlier entries have higher priority and take precedence over later
439+
entries. _The general rule is that conditions should be from most specific to
440+
least specific in object order_.
440441

441442
Other conditions such as `"browser"`, `"electron"`, `"deno"`, `"react-native"`,
442-
etc. are ignored by Node.js but may be used by other runtimes or tools.
443-
Further restrictions, definitions or guidance on condition names may be
444-
provided in the future.
443+
etc. are unknown to, and thus ignored by Node.js. Runtimes or tools other than
444+
Node.js may use them at their discretion. Further restrictions, definitions, or
445+
guidance on condition names may occur in the future.
445446

446447
Using the `"import"` and `"require"` conditions can lead to some hazards,
447-
which are explained further in
448-
[the dual CommonJS/ES module packages section][].
448+
which are further explained in [the dual CommonJS/ES module packages section][].
449449

450450
Conditional exports can also be extended to exports subpaths, for example:
451451

@@ -1128,10 +1128,11 @@ The `conditions` property on the `context` is an array of conditions for
11281128
for looking up conditional mappings elsewhere or to modify the list when calling
11291129
the default resolution logic.
11301130

1131-
The [current set of Node.js default conditions][Conditional exports] will always
1132-
be in the `context.conditions` list passed to the hook. If the hook wants to
1133-
ensure Node.js-compatible resolution logic, all items from this default
1134-
condition list **must** be passed through to the `defaultResolve` function.
1131+
The current [package exports conditions][Conditional Exports] will always be in
1132+
the `context.conditions` array passed into the hook. To guarantee _default
1133+
Node.js module specifier resolution behavior_ when calling `defaultResolve`, the
1134+
`context.conditions` array passed to it _must_ include _all_ elements of the
1135+
`context.conditions` array originally passed into the `resolve` hook.
11351136

11361137
```js
11371138
/**

0 commit comments

Comments
 (0)