Skip to content

doc: explain fallback arrays in package exports targets - #67393

Open
manusingh090 wants to merge 1 commit into
nodejs:mainfrom
manusingh090:doc-exports-array-targets
Open

manusingh090 wants to merge 1 commit into
nodejs:mainfrom
manusingh090:doc-exports-array-targets

Conversation

@manusingh090

Copy link
Copy Markdown
Contributor

The "exports" field definition lists string[] as an accepted type, but
packages.md never explains how an array of targets is resolved. This has
led people to assume an array falls back to the next file when the first
one does not exist (see the linked issue), which is not what happens.

This adds a "Target fallback arrays" section after "Nested conditions"
that documents:

  • an array can be used anywhere a target is accepted, in both "exports"
    and "imports", and items are tried in order;
  • an item is skipped only if it is an invalid target or a conditions
    object with no matching condition;
  • file existence is not checked, so a valid first target that points to a
    missing file fails instead of falling through to the next item;
  • an empty array means the subpath is not exported, and if every item is
    invalid the last error is thrown.

The wording follows PACKAGE_TARGET_RESOLVE in esm.md and
resolvePackageTarget() in lib/internal/modules/esm/resolve.js.

Verification

Tested with a small package in node_modules on Node.js ,
using both require() and import():

exports target Result
["./nope.js", "./b.js"] module not found
["../outside.js", "./b.js"] loads ./b.js
[{ "browser": "./nope.js" }, "./b.js"] loads ./b.js
[] ERR_PACKAGE_PATH_NOT_EXPORTED
["../x.js", "../y.js"] ERR_INVALID_PACKAGE_TARGET

node tools/lint-md/lint-md.mjs doc/api/packages.md passes.

AI disclosure

I used an AI coding assistant to help read the resolver code and draft the
text. I reviewed the section against the resolver source and ran the tests
above myself.

Fixes: #58600

The "exports" field type lists `string[]`, but the packages
documentation never describes how an array of targets is resolved.
Document that items are tried in order, that only invalid targets and
unmatched conditions are skipped, and that a missing file does not
cause the next item to be tried.

Fixes: nodejs#58600
Signed-off-by: Manjeet Singh <024manjeetsingh@gmail.com>
@nodejs-github-bot

Copy link
Copy Markdown
Collaborator

Review requested:

  • @nodejs/loaders

@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to Node.js documentation. label Nov 10, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Welcome to Node.js, and thank you for your first contribution!

Before review, please take a moment to read:

Please make sure every commit is signed off. For a first pull request, GitHub Actions require collaborator approval and Jenkins CI must be started by a collaborator or triager, so an initial wait is normal.

@ljharb ljharb left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

LGTM

@JakobJingleheimer JakobJingleheimer added the commit-queue PRs queued for automated landing through the Commit Queue. label Nov 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

commit-queue PRs queued for automated landing through the Commit Queue. doc Issues and PRs related to Node.js documentation.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Missing documentation for exports alternative paths

5 participants