From b61ab0b38819825391f5be421b106deb50c905c3 Mon Sep 17 00:00:00 2001 From: Ji Hoon Kang Date: Wed, 12 Aug 2026 20:31:04 +0900 Subject: [PATCH] doc: document exports target fallback arrays The `"exports"` field accepts an array of targets, but the only trace of it in the documentation was the `string[]` in the field's type notation. Nothing described when Node.js moves on to the next item. Document the three cases that skip an item: unrecognized target syntax, an object whose conditions do not match, and `null`. Also state that a missing file is not one of them, since targets are matched without checking the filesystem, so an array of valid paths always resolves to the first one. The syntax case comes from review feedback left on an earlier attempt that was closed without landing: a version that predates a given target form treats that form as invalid and falls through, which is what makes these arrays useful for compatibility. Fixes: https://github.com/nodejs/node/issues/58600 Refs: https://github.com/nodejs/node/pull/63340 Signed-off-by: Ji Hoon Kang --- doc/api/packages.md | 47 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/doc/api/packages.md b/doc/api/packages.md index c4781eca1062..153e666f85f1 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -496,6 +496,52 @@ substituted into a target pattern. } ``` +### Target fallback arrays + +An export target can be an array of targets. Node.js tries each item in order +and uses the first one it can resolve: + +```json +// package.json +{ + "name": "my-package", + "exports": { + ".": [ + { + "import": "./index.mjs", + "require": "./index.cjs" + }, + "./index.cjs" + ] + } +} +``` + +An item is skipped, and resolution continues with the next one, when: + +* Node.js does not recognize the target's syntax. A Node.js version released + before a given target form existed treats that form as invalid and falls + through to the next item. This is what makes fallback arrays useful for + compatibility: a newer form can be listed first and a target understood by + older versions second. +* The target is an object and none of its conditions match the current + environment. +* The target is `null`. + +A missing file does **not** trigger the fallback. Targets are matched +without checking whether the file they point to exists, so an array of +paths that are all valid always resolves to the first one. + +If every item is skipped, the result depends on why: + +* An empty array, or an array in which every item is `null`, makes the + subpath behave as if it were not exported. +* If an item was skipped because its syntax was invalid and no later item + resolved, that error is thrown. + +Fallback arrays are also supported in [`"imports"`][] and in +[conditional exports][], including within [nested conditions][]. + ### Exports sugar