Skip to content

Commit e386188

Browse files
Derek LewisMylesBorins
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 <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>
1 parent e273edf commit e386188

1 file changed

Lines changed: 14 additions & 13 deletions

File tree

‎doc/api/esm.md‎

Lines changed: 14 additions & 13 deletions
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

@@ -1154,10 +1154,11 @@ The `conditions` property on the `context` is an array of conditions for
11541154
forlookingupconditionalmappingselsewhereortomodifythelistwhencalling
11551155
thedefaultresolutionlogic.
11561156

1157-
The [currentsetofNode.jsdefaultconditions][Conditionalexports] willalways
1158-
beinthe`context.conditions`listpassedtothehook. Ifthehookwantsto
1159-
ensureNode.js-compatibleresolutionlogic, allitemsfromthisdefault
1160-
conditionlist**must**bepassedthroughtothe`defaultResolve`function.
1157+
Thecurrent [packageexportsconditions][ConditionalExports] willalwaysbein
1158+
the`context.conditions`arraypassedintothehook. Toguarantee_default
1159+
Node.jsmodulespecifierresolutionbehavior_whencalling`defaultResolve`, the
1160+
`context.conditions`arraypassedtoit_must_include_all_elementsofthe
1161+
`context.conditions`arrayoriginallypassedintothe`resolve`hook.
11611162

11621163
```js
11631164
/**

0 commit comments

Comments
 (0)