Revisit dot-main in exports field

[jkrems]

Originally the exports proposal had a way to specify the main field as well. The following was the equivalent of setting main to './lib/entry.mjs':

{
  "exports": {
    ".": "./lib/entry.mjs"
  }
}

We discarded this for two reasons:

1. Without dual-mode, having two separate values seemed confusing.
2. There were educational and aesthetic concerns with a property key that's just "." without additional context.

But with fallbacks and/or differential serving, we run into a new reason for wanting this second key: Backwards compatibility.

The problem is that if I'm maintaining a package std-x-polyfill and I want to fall back to the native std:x module where it's available, I could express it like this:

{
  "main": ["std:x", "./lib/x-polyfill.cjs"]
}

The problem is now: This package cannot be used in anything but the latest version of node. Older versions will not recognize this kind of main field. If we'd support exports[.] as an alternative with higher priority, the problem can be solved (if a bit verbose):

{
  "main": "./lib/x-polyfill.cjs",
  "exports": {
    ".": ["std:x", "./lib/x-polyfill.cjs"]
  }
}

[ljharb]

i'm not aware of any proposal that would ever alter how "main" works, including adding array support.

What I'd expect is something like this:

{
  "main": "./path",
  "exports": {
    "./path": ["std:x", "./lib/x-polyfill.cjs"]
  }
}

with a path.js as a backwards-compat fallback.

[guybedford]

Supporting relative ./paths on the LHS in exports is a sort of internal rewriting system.

The concern with these approaches is that you can import an absolute file path, but not necessarily actually get it when you load it! So there is a lack of transparency to the user.

Contrast this with exports, where the package name boundary naturally forms the encapsulation, instead of it applying to all types of importing. Users already know there is some indirection with package imports as import 'pkg' will import the main, so this sort of naturally extends to the package subpaths when importing the bare specifier. While importing /path/to/file.js suddenly loading another file is quite a different thing.

The point being, if we want to do "internal rewrites" that is a decision I think we should make very carefully thinking about the usability implications, and justified based on its unique merits.

[jkrems]

@ljharb Your solution seems to leak the existence of the polyfill onto the exports while also assuming that exports are something happening after main, adding one more level of indirection. I think both are surprising. Exports, unlike browser, is not an environment-specific override. It's a first-class mapping, just like main. So it applying after main seems counterintuitive.

[ljharb]

Right - i see it as more of a virtual filesystem, which to me “main” sits on top of - iow i do not see main and exports as siblings, but rather “main” as a high level thing and “exports” as a low level thing.

[jkrems]

I'm not sure I follow how main is any different here.main maps "foo" to an internal path, exports maps "foo/bar" to an internal path. The only difference is the substring after "foo" which is "" for main.

If we start asking people to add intermediate junk paths to exports so they can use its features for main, it seems like we're actively undoing the clean interface main+exports could provide. Now I suddenly need to support both "foo" and "foo/<some-opaque-id>" as my interface..?

[ljharb]

Maybe I’m not clear on what you want either. I don’t think the format of “main” should ever change. What exact goal do you want to achieve that couldn’t be done with an unchanging main format?

[jkrems]

The use case is in the original issue: I want a simple poly fill package that falls back to a native module if it exists. The package has a single entry point, so I don’t need to (and don’t want to) expose additional paths.

The same idea applies for something like React where I might want to declaratively expose a dev and production build, depending on the env. It’s seems weird if that works for subpaths but not for the package name itself.

[ljharb]

then why specify main at all? You can have an exports with just “index.js” in it.

[jkrems]

Right, that's what this is suggesting. Maybe the confusion is that in the current implementation, exports cannot be used to specify main? We explicitly removed that feature to prevent dual-mode packages.

[ljharb]

We explicitly removed that feature to prevent dual-mode packages.

It would certainly allow packages that worked on both old and new node, but not a package that was both CJS and ESM (which is what some have expressed reservations about). I don't recall any concern about allowing a package to have different entry points for entirely different versions of node.

[jkrems]

That’s the hope! But there are some concerns that it may be confusing to have one main for old node, one implicit main for old node (index), and one main for new node in exports. It’s possibly confusing but I’m not sure if we have a better option.

…

On Tue, Aug 6, 2019 at 12:57 PM Jordan Harband ***@***.***> wrote: We explicitly removed that feature to prevent dual-mode packages. It would certainly allow packages that worked on both old and new node, but not a package that was both CJS and ESM (which is what some have expressed reservations about). I don't recall any concern about allowing a package to have different entry points for entirely different versions of node. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#368?email_source=notifications&email_token=AAEKR5EPM4PWZI7UTGN5Z2LQDHJRVA5CNFSM4IJSAPTKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD3WJBVQ#issuecomment-518820054>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAEKR5HN6NS72L2FJSV4KM3QDHJRVANCNFSM4IJSAPTA> .

[ljharb]

If exports couldn't specify "main", but it could overwrite whatever "main" is pointing to - wouldn't that solve all of our concerns?

Dual-mode packages would still not be enabled; dual-node packages would; "main" wouldn't have to change (ie, break) its format; etc.

The only downside is that you might have to repeat the RHS of "main", in the LHS of "exports" - but that explicitness kind of seems like a pro, not a con?

[jkrems]

I think that's a reasonable outcome. Right now we have an explicit check that prevents exports from overwriting the value of main and we could just remove this check if nobody else objects.

[GeoffreyBooth]

An overwrite makes much more sense to me than an extends. In other words, if "exports" is set and defines ".", that defines the package entry point; and that’s it. "main" is irrelevant, whether or not it’s even defined. "main" would only apply to older versions of Node for such a package.