Add an exports "browser" entry

[guybedford]

It is great to see this package supporting the "exports" field so well.

This adds support for a "browser" entry as well in exports which is a tooling pattern that would be good to encourage as a way to support both the browser field and the exports field together in tools.

Questions / feedback welcome.

[ctavan]

Thanks for the contribution @guybedford !

Could you point us to further information regarding which bundlers support this new pattern already (or intend to support it)?

[guybedford]

I posted this issue as I noticed in jspm testing that browser workflows around uuid and "exports" support that they were always bringing in the Node.js builtins.

Node.js alludes to it in the docs at https://nodejs.org/dist/latest-v14.x/docs/api/esm.html#esm_conditional_exports.

Preact currently supports it in https://unpkg.com/preact@10.4.4/package.json.

jspm will be supporting it in the coming release. I'm not sure what Webpack support is looking like currently, @sokra may be able to share some info there.

If you'd rather wait for wider adoption feel free to leave this issue open or close, to wait until such a point as you feel it is clear there is a benefit to the project. I personally would recommend adding it though.

[ctavan]

I assume that jspm/jspm-cli#2494 is the corresponding jspm issue.

I'm generally happy to be an early adopter of such new semantics, however being an early adopter here also usually means additional effort in dealing with bug reports on this issue tracker. We had this already when adding pkg.exports support in the first place because people tried using it with early v13.x versions of Node.js where exports support was still behaving differently (see your tweet: https://twitter.com/guybedford/status/1235329049779634177).

I would prefer to have some clear intents to implement this from the relevant package managers which so far aren't super clear to me:

• Rollup: Support "exports" field in package.json rollup/plugins#208 (comment) was closed by @shellscape (/cc @lukastaegert)
• Webpack: Respect "exports" field in "package.json" webpack/webpack#9509 (comment) not sure if/how browser field will be supported (/cc @evilebottnawi @sokra)
• More in: Add bundlers and resolution jkrems/embracejs#1 (/cc @jkrems)

So if we manage to reach agreement that this will eventually be widely support, I'm happy to merge this. Since uuid is a very heavily depended-upon module it will certainly help discover edge cases because it's highly likely that somebody will stumble upon them…

[alexander-akait]

@ctavan The exports field supported only in webpack@5 (beta) WIP,
For web target:

• webpack/development/import/browser

It's actually a little trickier, I can provide more information if you need

Ref: webpack/webpack#10953

[ctavan]

Thanks for providing information on webpack, @evilebottnawi!

• webpack/development/import/browser

It's actually a little trickier, I can provide more information if you need

Which of the keys will win? For our use case it would be crucial that browser wins over import…

[alexander-akait]

If you do import from ESM module import wins over browser
If you do require from CommonJS require wins over browser

Just not it is WIP and we are open for feedback

[jkrems]

Hopefully the field should be matched in order. So if browser is listed first in the exports object, it will win. If bundlers implement a different precedence order, that should be fixed asap to make sure that the logic applies consistently across environments. :)

[ctavan]

Do we have guaranteed object key order in JSON/JavaScript?

[alexander-akait]

@ctavan Yes

[broofa]

From RFC7159 (emphasis mine):

An object is an unordered collection of zero or more name/value pairs...

[alexander-akait]

https://nodejs.org/api/esm.html

Condition matching is applied in object order from first to last within the "exports" object. The general rule is that conditions should be used from most specific to least specific in object order.

[jkrems]

@broofa Yeah, there was a discussion about this in the PR for node - it's a compromise between letter-of-the-law and usability. In practice JSON does have ordered keys because that property was viral. Some languages had ordered keys, their devs started to depend on it when reading JSON, and that expectation spread to consumers/producers from other languages.

By now all major JSON handling libraries we were able to find were preserving object order or had options to do it, generally speaking. The big gotcha are numerical properties in JS which we explicitly disallow inside of exports because of it.

[ctavan]

Wow. To be honest this doesn’t really make the whole pkg.exports feature less surprising, at least for somebody like me who was still assuming that this is a guarantee one should never rely on. I see that the discussion was lengthy and apparently I‘m in the camp of people who are extremely surprised by such behavior and also that ship seems to have sailed...

[guybedford]

@ctavan can you share what about the feature you find surprising here? Tools still have the ability to decide which exports they want to resolve. But by giving precedence ordering allows for cross-tooling determinism in how exports are selected for a given environment vector. The proposal to use ordering was also based on initial feedback from @sokra.

[broofa]

Deliberately implementing a feature to rely on key-ordering in a context where such ordering is not only unexpected, but expressly not guaranteed is going to cause problems. @devsnek had it right if order is important, use an Array.

[guybedford]

@broofa object order is very much guaranteed in JavaScript, can you clarify what about the ordering seems uncertain?

[jkrems]

Btw, if you prefer to be explicit about the ordering, you can do it:

  ".": [
    { "browser": "./dist/esm-browser/index.js" },
    { "require": "./dist/index.js" },
    { "import": "./wrapper.mjs" }
  ],

Afaik that should work as well and doesn't depend on object key order at the expense of being a bit more verbose.

[broofa]

@broofa object order is very much guaranteed in JavaScript, can you clarify what about the ordering seems uncertain?

• It's package.json
• JSON ≠ JavaScript
• JSON: "An object is an unordered collection..."

Reordering keys-pairs in JSON shouldn't change the semantics. E.g. If you alphabetize keys (say, for readability, or to limit diff churn) you should be able to do so without getting bit in the ass by it. I can't tell you how thrilled I am to discover that's no longer the case. 😢

[guybedford]

I see what you mean. We did do quite a bit of research into existing JSON tooling to verify ordering would be compatible with most workflows and were very much aware of the problem but made a decision as a group here. Jan's suggestion is a way to get around that concern if you prefer.

It feels like this thread has gone somewhat off track from the initial intention which was to help aid users in adopting that this package is already shipping the "exports" field with browser builds.

On the same note, another thing I did notice is that users doing eg require('uuid/v4') will no longer be able to do that with the "exports" field support shipped already, since no subpaths were defined.

How you want to handle these cases is entirely up to you here, the last thing I want to do is force any approach, but just happened to notice these cases so thought I would share the suggestion.

[sokra]

The json spec doesn't say it's unordered. That's only a interpretation of the website

From the spec:

and does not assign any
significance to the ordering of name/value pairs. These are all semantic considerations that may be defined by
JSON processors or in specifications defining specific uses of JSON for data interchange.

The json spec leave it open for the specification that is defining the use of the JSON to define a semantic to the ordering. This is what the exports spec does.

That also means that it's not in general safe to reorder keys in JSON. It depends on the usage of the JSON.

[jkrems]

From the spec [...]

The spec in question is ECMA-404, quote is from section 6 ("Objects"). See: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf. Linking here since it took me a second to find the source.

[sokra]

Another note: this PR should be considered as bugfix (at least for webpack 5 users).
As the exports field have higher priority than the browser, main and module field, having an exports field without a browser condition will break browser usage. Resolving would follow the exports field import condition and would use the node version.

[ctavan]

I see what you mean. We did do quite a bit of research into existing JSON tooling to verify ordering would be compatible with most workflows and were very much aware of the problem but made a decision as a group here. Jan's suggestion is a way to get around that concern if you prefer.

It feels like this thread has gone somewhat off track from the initial intention which was to help aid users in adopting that this package is already shipping the "exports" field with browser builds.

I agree, we're moving off-topic.

Apparently both @broofa and me were just a little shocked to discover that reordering object keys in a JSON file – something we always assumed to be an operation with NO semantic meaning – will suddenly break stuff.

Thanks @sokra for bringing to my attention that the spec apparently leaves this open (and thanks to @jkrems for linking the PDF, was just googling for this myself)

On the same note, another thing I did notice is that users doing eg require('uuid/v4') will no longer be able to do that with the "exports" field support shipped already, since no subpaths were defined.

Yes, this was a deliberate choice. We already deprecated deep imports 2 major versions ago and removed support for them 1 major version ago.

That said, I appreciate that you brought the fact, that the browser key will actually become a thing and I will definitely do some more testing on my own in order to land support for this feature!

---

Now back to the actual change (and since @sokra and @evilebottnawi are already in this thread): With the current ordering, webpack will always pick the browser key, when bundling for a web target, irrespective if this library is imported or required, do I get that right? So in that case – unlike with Node.js – webpack will always use the esm build for bundling irrespective of whether it is being included from an esm module or from a CommonJS module?

And then, when bundling for Node.js: Could we end up having the uuid library included twice in the bundle if it is required and imported at the same time somewhere in the bundle's dependency tree (a bit similar to the dual-package-hazard of Node.js)?

[ctavan]

Another note: this PR should be considered as bugfix (at least for webpack 5 users).
As the exports field have higher priority than the browser, main and module field, having an exports field without a browser condition will break browser usage. Resolving would follow the exports field import condition and would use the node version.

That brings another potential issue to my attention: For Node.js builds webpack is supposed to pick up the module field, i.e. ./dist/esm-node/index.js If exports has higher priority, I guess we currently also get the wrong module for Node.js bundles (./wrapper.mjs which only wraps the CommonJS build). Is that the case @sokra? (And what key could we use to resolve that?)

[sokra]

With the current ordering, webpack will always pick the browser key, when bundling for a web target, irrespective if this library is imported or required, do I get that right?

Yes. While you could technically do a separation here with nested conditions this is unneeded and may even hurts bundle size. Since all bundlers support to require esm I would recommend to keep it this way.

Could we end up having the uuid library included twice in the bundle if it is required and imported at the same time somewhere in the bundle's dependency tree (a bit similar to the dual-package-hazard of Node.js)?

Yes this can happen.

For Node.js builds webpack is supposed to pick up the module field, i.e. ./dist/esm-node/index.js If exports has higher priority, I guess we currently also get the wrong module for Node.js bundles

Yes. webpack with node target would pickup wrapper.mjs. Not sure if you consider this as problem, but it make sense in my opinion as a node bundle behaves like non-bundled node.

And what key could we use to resolve that?

There is a webpack condition, but this was intended for edge cases.

But I see the intend, for systems that support to require esm you want to always use esm. Maybe we need a separate condition here (module)?

[ctavan]

With the current ordering, webpack will always pick the browser key, when bundling for a web target, irrespective if this library is imported or required, do I get that right?

Yes. While you could technically do a separation here with nested conditions this is unneeded and may even hurts bundle size. Since all bundlers support to require esm I would recommend to keep it this way.

This is fine and exactly what I want: I always want webpack to pick what's behind the pk.exports.browser key!

Could we end up having the uuid library included twice in the bundle if it is required and imported at the same time somewhere in the bundle's dependency tree (a bit similar to the dual-package-hazard of Node.js)?

Yes this can happen.

OK, but only for Node.js right? Not for a browser bundle (if the browser key is specified)?

For Node.js builds webpack is supposed to pick up the module field, i.e. ./dist/esm-node/index.js If exports has higher priority, I guess we currently also get the wrong module for Node.js bundles

Yes. webpack with node target would pickup wrapper.mjs. Not sure if you consider this as problem, but it make sense in my opinion as a node bundle behaves like non-bundled node.

While I don't really get the use case of bundling for Node.js (I assume serverless cloud functions?!),
if people bundle for Node.js with webpack, I would prefer webpack to behave like in the browser case and always pick the same esm build, irrespective of whether the module was imported from another esm or required by a CommonJS module. I would find it highly confusing if I get the uuid library bundled twice just because I bundle for Node.js instead of for the browser.

And what key could we use to resolve that?

There is a webpack condition, but this was intended for edge cases.

But I see the intend, for systems that support to require esm you want to always use esm. Maybe we need a separate condition here (module)?

So what we want for this module is the following:

1. ./dist/index.js for Node.js CommonJS
2. ./wrapper.mjs for Node.js ESM, it only wraps the CommonJS module to avoid the dual package hazard.
3. ./dist/esm-browser/index.js for any browser bundle
4. ./dist/esm-node/index.js for any Node.js bundle irrespective of whether it's imported or required to ensure proper tree shaking. I don't want the package twice in the bundle just because pkg.exports.require and pkg.exports.import keys happen to be defined.

So far we could achieve this by specifying 1. and 2. in pkg.exports, 3. through pkg.browser and 4. through pkg.module. This worked well for webpack 4 thanks to the resolve.mainFields defaults and is also how e.g. rollup happens to behave.

Now that pkg.exports takes precedence over pkg.browser and pkg.module it looks like we need a way to provide webpack with the explicit entry point for Node.js builds , something that takes over the role of pkg.module.

Not sure if a new module key would be such a good naming choice since in my opinion this has never been a very self-explaining name. Maybe instead node, similar to browser?

So yes, I do believe that we need an additional key to be able to restore the old webpack 4 behavior.

[jkrems]

For 4, why couldn't it just use dist/index.js and wrapper.mjs? It feels surprising that it should pick a different implementation just because the code got bundled. If a bundler supports bundling specifically for node, it should support CommonJS and handle this well without needing special logic beyond the existing cases (1) and (2).

[guybedford]

@ctavan the browser bundle should certainly be as optimized as possible, but the standard Node.js convention is not to worry so much about bundling and code size optimizations as they aren't nearly as critical as they are for the browser environment.

If we were talking about 100s of KB here that would be another story, but it seems the numbers are well under 100KB as far as I can tell which is well under a milisecond of startup cost to your Node.js users.

As long as Webpack is using the "browser" field for your primary bundling scenarios, and that is well-optimized, then surely that handles the major upgrade path here?

[sokra]

cc @lukastaegert for rollup

I also see the need of adding an additional condition for that case. For webpack it doesn't matter so much, but rollup is really eager to prefer ESM over CJS and not using a ESM wrapper approach. If you want to convince rollup to prefer exports over module that case should be covered.

I would go with a "module" condition, even while it's not super descriptive, it's short and better than the alternative names I could come up with. It could read as

"module" - would prefer an (ES)module in general. (implicitly means it's also allowed at all positions)

Technically a commonjs makes also sense but I think nobody would set this anyway.

For a package.json this could be used:

  "main": "./dist/index.js",
  "module": "./dist/esm-node/index.js",
  "browser": "./dist/esm-browser/index.js",
  "exports": {
    ".": {
      "browser": "./dist/esm-browser/index.js",
      "module": "./dist/esm-node/index.js",
      "require": "./dist/index.js",
      "default": "./wrapper.mjs"
    },
    "./package.json": "./package.json"
  },

I intentionally omitted the case where a browser build should ship commonjs instead of ESM. Technically this could be covered but is not relevant in practive and only make the package.json more verbose.

For the curious...

  "main": "./dist/index.js",
  "module": "./dist/esm-node/index.js",
  "browser": {
    "./dist/esm-node/index.js": "./dist/esm-browser/index.js",
    "./dist/index.js": "./dist/browser.js"
  },
  "exports": {
    ".": {
      "browser": {
        "module": "./dist/esm-browser/index.js",
        "require": "./dist/browser.js",
        "default": "./dist/esm-browser/index.js",
      },
      "module": "./dist/esm-node/index.js",
      "require": "./dist/index.js",
      "default": "./wrapper.mjs"
    },
    "./package.json": "./package.json"
  },

Assuming everybody prefers exports over module over main and at least the following conditions are used (condition in brackets are not significant in this example):

usage	node	bundler (for browser)	bundler (for node)
import "..."	(node), (import)	browser, (import), module	(node), (import), module
require("...")	(node), require	browser, require, module	(node), require, module

Example with the package.json above (independent of exports field support of bundlers):

usage	node	bundler (for browser)	bundler (for node)
import "uuid"	./wrapper.mjs	./dist/esm-browser/index.js	./dist/esm-node/index.js
require("uuid")	./dist/index.js	./dist/esm-browser/index.js	./dist/esm-node/index.js

[lukastaegert]

If you want to convince rollup to prefer exports over module that case should be covered.

Exactly. There are also other tools that have advanced needs in that direction, e.g. Vite, Snowpack, es-dev-server. I just wrote some ideas up myself that I would expect from such an entry point here: rollup/rollup#3514 (comment)

If there is interest, I could try to merge your ideas with mine to form a spec to move things forward. module actually isn't the worst idea. And something to cover dev mode. Not sure when I will find time, though.

[lukastaegert]

Fun fact: At least Vite and es-dev-Server are currently using or at least offering @rollup-plugin-commonjs for their CJS interop...

[sokra]

Regarding browserDev: you can combine multiple conditions and there are browser and development conditions.

If you want a separate condition for real ESM running in the browser, I would prefer it to use a separate name instead of changing browser (e. g. web or web-module) as this would otherwise hinder easy migration from main, module, browser to exports. Or maybe the engines field is more suited to express the fact that this is real web compatible.

Do we need this anyway? Would you ever pass a different value than for browser?

[lukastaegert]

As I see it, current browser is like "only do things that would work in a browser but I do not care about module semantics" or in other words it is a messy thing that does not work well for bundler-free dev setup tooling. With your suggestion as "module" is still up for grabs, I would use the opportunity to define some stricter semantics for exports.module as well as exports.module.browser. I agree that there really is no advantage since if your library supports the stricter semantics, it also supports the semantics of browser. It is more about clearly defining specs to develop libraries against for the next generation of tools. Which is why I was originally hoping to gain support to formulate those expectations for browser directly.

[sokra]

You could change the limitations, but in the end it's up to the user to provide a compatible package. Especially if you change the meaning of browser in the package.json, I would expect that only very few people really change the code style before adding an exports field. That would result in the fact that you can't trust these limitations and they loose their value. Therefore I think it's better to add a separate condition name for that.

There is also the migration aspect. I think there should exist a 1 to 1 mapping from old style to exports field to allow easy migration and avoid confusion. When semantic would change that would hinder migration and adoption.

Even when less strict semantic there are a couple benefits of the exports field that are value-able:

• Alternative to process.env.NODE_ENV -> development condition
• Private inner paths are unaccessible

I think we are on a good way regarding these limitations anyway:

Stage 4 is already recommended for published packages, and this seem to work quite ok.

type: "module"/.mjs will enforce extensions for imports in webpack.

webpack 5 will error by default when using node built-in modules.

We could display more warnings when a module flags itself as "wannabe web esm compatible", but I don't think such a flag fits into the exports field. That would be something for engines.

[lukastaegert]

True. But personally, I do not see why migration to exports is a goal in itself. There will be packages that are not migrated for a long time so I expect support for old-style fields will not be removed too soon. Not rethinking what goes into each field is a missed chance, but maybe the ship for exports.browser has long sailed if you have been encouraging its use for a while. My hope was to fix this in some way: https://twitter.com/youyuxi/status/1266514731822714880
IMO browser is broken.

[lukastaegert]

Actually, this is more spot-on: https://twitter.com/mjackson/status/1266527272439181312

[lukastaegert]

That being said, I would hope browser dies in favour of something useful that works in browsers.

[lukastaegert]

Going back to the idea of module, I think it is not a very helpful name, the only reason to use it is tradition. As it is meant to describe environments that only support modules, I would go for "moduleOnly": .

[jkrems]

I think moduleOnly may be even more confusing because it’s for environments that treat CommonJS and ESM as somewhat interchangeable. Maybe “bundle” would be more appropriate. But as Guy said further up: this sound like working around tooling restrictions which seems dangerous to encode all over the ecosystem.

[sokra]

I wouldn't say that browser is broken, but it maybe has a different propose. It doesn't say anything about the module format, only about the environment the code will run in. You can't assume that you find ESM in the browser field. That's an incorrect assumption.

My fear is that even if we would define exports.browser different than browser people would still publish the same things there.

[sokra]

moduleOnly would not work for rollup or webpack as they both also support CJS, so that would not be supporting only modules

[sokra]

bundle might be inappropriate for non-bundlers like vite or snowpack

[lukastaegert]

I think moduleOnly may be even more confusing because it’s for environments that treat CommonJS and ESM as somewhat interchangeable

I think you completely missed the point, it is for environments that do not understand CommonJS AT ALL. But so did @sokra:

moduleOnly would not work for rollup or webpack as they both also support CJS, so that would not be supporting only modules

I think you got this one the wrong way around. moduleOnly means that this entry point promises that here you will only get ES modules all the way down. Also as a side-note, vanilla Rollup does not support CJS.

A tool can choose to prefer this entry over other alternatives if of course it does not support anything but modules, but also if this would provide a better result. moduleOnly has two advantages, the second being that there is no double-state hazard that needs to be fixed. If such an entry does not exist, one would fall back to other alternatives, similar to when there is no browser entry even though you would like to have one.

It would also be possible to write a simple CLI validation tool that checks if the moduleOnly entries of a package actually satisfy what is promised. And I guess I would do this if we want to move this forward and ever gain traction. As an example right now, many people have no idea that their ESM output is broken if they mix in a require statement. This would also be about education for library authors.

[ctavan]

@sokra @lukastaegert I have just created webpack/webpack#11014 and would like to move the discussion there. I think the discussion we're having here is pretty important to the whole bundler ecosystem and I don't want it to live in the pull request comments of the uuid module.

[guybedford]

I think it is honestly a complete and utter pipe dream to expect users of npm packages to be able to drop CommonJS support. It will take 10 years for this to happen, and that one dependency that is useful might be CommonJS to be a blocker to such a workflow seems a very fragile and arbitrary development restriction.