Affected URL(s)

https://nodejs.org/api/packages.html#subpath-exports

Description of the problem

Hello Node.js documentation team,

I would like to request an update or addition to the Packages documentation, specifically the "Subpath Exports" section, to clearly explain the rules regarding invalid path segments in the exports field of package.json.

Background

Currently, the documentation states that all paths in "exports" must be relative file URLs starting with ./. However, it does not explicitly mention that certain path segments—such as .. (parent directory), . (current directory), and their URL-encoded equivalents—are forbidden within export targets. This rule is enforced by Node.js and is critical for package authors to understand, as using these segments will cause runtime errors or warnings.

Why this matters

• Many package authors like msw and users are unaware that targets like "./../lib/index.js" are invalid and will not work.
• The Node.js resolver enforces this rule strictly, but the documentation does not make it obvious.
• This leads to confusion, unexpected errors, and wasted debugging time.

What I'm requesting

• A dedicated section or callout in the "Subpath Exports" documentation that:
  • Clearly lists which path segments are forbidden (e.g., .., ., node_modules, and their URL-encoded forms).
  • Explains the rationale (to prevent escaping the package boundary and ensure encapsulation).
  • Provides examples of both valid and invalid exports targets.
  • Optionally, references the relevant part of the Node.js source code or spec for advanced users.
  • If maintainers are willing to receive any contribution regarding this, I can work on this.

Example

Invalid path segments in exports targets

The target of an export subpath must not contain any segment that is .., ., node_modules, or their URL-encoded equivalents. For example, "./../lib/index.js" is invalid and will cause an error.
the entire regex representation of invalid path segments: const invalidSegmentRegEx = /(^|\\|\/)((\.|%2e)(\.|%2e)?|(n|%6e|%4e)(o|%6f|%4f)(d|%64|%44)(e|%65|%45)(_|%5f)(m|%6d|%4d)(o|%6f|%4f)(d|%64|%44)(u|%75|%55)(l|%6c|%4c)(e|%65|%45)(s|%73|%53))?(\\|\/|$)/i;

References

• Node.js ESM resolver source code
• Related issues in bundlers and package managers (example)

Thank you for your work on Node.js and its documentation!
This clarification would help package authors and users avoid common pitfalls and improve compatibility across the ecosystem.