Skip to content

doc: explain exports target fallback arrays #63340

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
MukundaKatta wants to merge 1 commit into from
+34 −0
Closed

doc: explain exports target fallback arrays #63340

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions doc/api/packages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -496,6 +496,40 @@ substituted into a target pattern.
}
```

#### Package target fallback arrays

Export targets can also be arrays. Each array item is tried in order until
Node.js finds a target that resolves for the current package subpath and
Copy link
Copy Markdown
Member

@ljharb ljharb May 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it also tries until it can understand the syntax - for example, in node versions 13.2-13.7 iirc, the only format supported is a string, so these versions will skip an object and fall back to the next item.

conditions. Array items can be string targets, `null`, nested condition
objects, or nested arrays, and string targets follow the same validation rules
described above.

```json
// package.json
{
"name": "my-package",
"exports": {
".": [
{
"node": "./node.js",
"default": "./universal.js"
},
"./fallback.js"
]
}
}
```

In this example, Node.js resolves `my-package` to `./node.js` because the
`"node"` condition matches. A runtime that ignores `"node"` could still resolve
the first array item through `"default"`. If the first array item does not
resolve for the active conditions, Node.js continues to the next item.

Node.js does not check whether a resolved file exists before selecting an array
item. For example, `["./missing.js", "./fallback.js"]` resolves to
`./missing.js`; the missing file error does not cause Node.js to try
`./fallback.js`.

### Exports sugar

<!-- YAML
Expand Down
Loading