Repository: node
Issue: doc: What is the spec regarding Package exports target fallbacks
Labels: doc,esm

# 📗 API Reference Docs Problem

<!--

Thank you for wanting to make nodejs.org better!

This template is for issues with the Node.js API
reference documentation.

For problems with nodejs.org beyond the API
reference documentation, please open an issue
using the issue tracker for our site repository.

  https://github.com/nodejs/nodejs.org

For more general support, please open an issue
using the issue tracker for our help repository.

  https://github.com/nodejs/help

---

For the issue title, please enter a one-line
summary after “doc: ” (preferably 50 characters
or less and no more than 72).

The “✍️” are placeholders signifying requests for
input. Replace them with your responses.

If you are unsure of something, do your best.

-->

<!-- The output of “node --version”. -->

- **Version**: ✍️ 16.13.0

<!-- The output of “uname -a” (UNIX) or version
and 32-bit or 64-bit (Windows). -->

- **Platform**: Linux development 4.19.0-18-amd64 # 1 SMP Debian 4.19.208-1 (2021-09-29) x86_64 GNU/Linux

<!-- The name of affected core module. -->

- **Subsystem**: esm

## Location

_Section of the site where the content exists_

Affected URL(s):

- https://nodejs.org/api/packages.html

## Description

_Concise explanation of the problem_

<!-- If applicable, include any screenshots that
may help solve the problem. -->

The esm resolve implementation will recursively process targets https://github.com/nodejs/node/blob/a37b9c80ef837de5fc99d750c3597d32ad3814b0/lib/internal/modules/esm/resolve.js#L527-L555.

The following work:

```json
{
  "name": "v",
  "version": "1.0.0",
  "description": "",
  "exports": {
    ".": [{
      "default": "./index.mjs"
    }],
    "./one": [[{
      "default": "./one.mjs"
    }]]
  }
}
```
```
import * as v from 'v'
log(v)

import * as v1 from 'v/one'
log(v1)
```
```
[Module: null prototype] {
  __filename: '/home/debian/projects/jasonkuhrt/research-node-package-exports/node_modules/v/index.mjs'
}
[Module: null prototype] {
  __filename: '/home/debian/projects/jasonkuhrt/research-node-package-exports/node_modules/v/one.mjs'
}
```

But the Package.json schema in VSCode says:

<img width="391" alt="CleanShot 2021-11-20 at 10 00 55@2x" src="https://user-images.githubusercontent.com/284476/142731150-6dc5d7ef-72a1-47de-a22e-f903e41297d1.png">

Unrelated to this issue but even that schema validation error message is inconsistent. It says `string, null` yet is not catching the above case which should be wrong too, then.

I'd like to know:

1. Is the VSCode Package.json schema wrong or is Node wrong?
2. The docs basically mention nothing about these accepted patterns. If its so expressive as to be difficult to exhaustively explain every permutation, fine, but right now fallbacks is [barely mentioned](https://nodejs.org/api/packages.html#exports-sugar). Thus I think there is plenty room for more docs here.
3. Webpack calls target arrays ["alternatives"](https://webpack.js.org/guides/package-exports/#alternatives) while Node calls them ["fallbacks"](https://nodejs.org/api/packages.html#exports-sugar): which is it?

A formal spec would be awesome, does one exist? And if so, the docs should link to it I think.

---

<!-- Use “[x]” to check the box below if you are
interested in contributing. -->

- [x] I would like to work on this issue and
      submit a pull request.