Conditional exports naming usability discussion

[guybedford]

Further to discussions from today re resolver stability and trying to incorporate the current feedback on conditional exports I've posted the PR at nodejs/node#30799 to open discussion around conditional exports naming and behaviours.

From the PR description -

A major priority for the modules implementation is resolver stability, and the dual mode story through conditional exports is a big remaining piece of this.

Common usability feedback out of various discussions on conditional exports so far has been that the "default" field may be seen to be a confusing name, and that it isn't clear when the "require" condition will match either.

To try and improve the overall usability this PR makes the following condition name changes:

• Add a new "import" condition as the converse of the "require" condition, only applying for the ESM loader.

All conditions (except for "default") remain behind the --experimental-conditional-exports flag.

This makes the dual mode workflow look like:

{
  "type": "module",
  "main": "./index.cjs",
  "exports": {
    "require": "./index.cjs",
    "import": "./index.js"
  }
}

instead of the previous:

{
  "type": "module",
  "main": "./index.cjs",
  "exports": {
    "require": "./index.cjs",
    "default": "./index.js"
  }
}

the UX improvement being that the former seems like it will look more natural to most users unfamiliar with "exports".

[ljharb]

Removing "default" will break the current implementation in node 13 for the packages I've published with "exports" - I hope we don't do that.

[GeoffreyBooth]

I like this direction. "module" and "commonjs" make far more sense to me. It’s immediately obvious what each one is for.

Furthermore, "module" is a better fallback/“for every runtime” key than "default". Every runtime that supports "exports" will support ESM, so they will all support "module", so we might as well make that the fallback key; and it’s better than "default" because "default" isn’t necessarily ESM whereas "module" is. That’s a big benefit.

We should remove "default" immediately, perhaps in the next minor release, to minimize the number of people impacted by the change. The feature has an experimental warning, so we can change or remove it at any time, and there’s no guarantee of backward compatibility.

[ljharb]

That we can technically get away with it doesn't mean that downstream users won't suffer as a result; this isn't imposing a cost on module authors, it's imposing a cost on their consumers.

Could we add and prefer "module" and "commonjs", but still support "default" until the next major?

[GeoffreyBooth]

We also need to add to the docs some information about how conditions are recursive. For example:

{
  "type": "module",
  "main": "./index.cjs",
  "exports": {
    "node": {
      "commonjs": "./index.cjs"
    },
    "module": "./index.js"
  }
}

This formulation should cause all Node consumers to load the CommonJS index.cjs; it’s as if the ESM version wasn’t shipped at all. But all other runtimes (browsers, Deno, etc.) would load the "module" key’s index.js. This is a way to avoid the dual package hazard, as there’s exactly one version of the package available for use in Node (in either ESM or CommonJS environments). This isn’t as good a solution as the ESM wrapper approach, as the latter provides named exports, but for a package like request that provides only a root export this works just as well.

[hybrist]

Rename the "default" condition to "module" with it only applying for the ESM resolver.

Let's please phrase this as: Remove the default condition and add a module condition. The default condition was sugar for a clean array fallback. If there's any restrictions on "module", it's fundamentally a different condition (which isn't bad, just something I think should be made explicit). So the correct way to rewrite this:

{
  "type": "module",
  "main": "./index.cjs",
  "exports": {
    "require": "./index.cjs",
    "default": "./index.js"
  }
}

Would be to use the non-default-using:

{
  "type": "module",
  "main": "./index.cjs",
  "exports": [{
    "require": "./index.cjs",
  }, "./index.js"]
}

There's other uses of default (e.g. "node" or "browser" vs. "default") where replacing default with module doesn't really make sense:

{
  "type": "module",
  "main": "./use-inline-crypto.cjs",
  "exports": {
    "node": "./use-node-crypto.cjs",
    "browser": "./use-web-crypto.cjs",
    "default": "./use-inline-crypto.cjs"
  }
}

There's no ES modules involved, so replacing "default" with "module" here would just break the package. But the following works perfectly fine:

{
  "type": "module",
  "main": "./use-inline-crypto.cjs",
  "exports": [{
    "node": "./use-node-crypto.cjs",
    "browser": "./use-web-crypto.cjs",
  }, "./use-inline-crypto.cjs"]
}

I'm a fan of the array fallbacks, so I can live with getting rid of "default". And I agree that adding a "module" condition makes sense, especially since we shipped without a "require" guard in 13 which limits what packages can do.

[coreyfarrell]

This proposed scheme is confusing to me as commonjs is a format which can be loaded by node.js import() but the commonjs export is only used for require(). The package.json#type field using commonjs and module to reflect the format adds to this confusion for me. I'd much prefer for commonjs / module within exports to indicate format rather than supported loader.

[hybrist]

I'd much prefer for commonjs / module within exports to indicate format rather than supported loader.

The confusing thing about the whole distinction is that we'll realistically not make this about the format. It will always be about the supported loader. E.g. require/commonjs guards can point to custom require hooks (e.g. .coffee) or native modules (.node) which isn't a CommonJS module but "something that refers to the require loader". Same with module: It's not ESM only. It's "things the import loader can load" which may include WASM for example. At least I wouldn't expect us to make up precedent rules between different file formats within the import loader. "Pick WASM first, then ESM" sounds super weird.

[bmeck]

I'd agree with @jkrems here, it gets more complicated if we use the term commonjs. For example, a commonjs file could use import() but it wouldn't use the commonjs condition. I'm more neutral on default/module/import though. I think part of this confusion might be the default not defining which system is being used on a glance and it will just take some repetition to learn, perhaps naming it import would have matched require more, but i doubt we will be adding other systems of loading code anytime in the foreseeable future so default seems fine to keep for me.

[GeoffreyBooth]

I'd much prefer for commonjs / module within exports to indicate format rather than supported loader.

The confusing thing about the whole distinction is that we'll realistically not make this about the format. It will always be about the supported loader.

Well that was what I liked about commonjs / module: that (I thought) it described the files in the package, not the loader to use. In general a package.json feels like it should be metadata about the package. Hence commonjs makes sense to me as “this is the CommonJS file for this path.” Even stuff like browser makes sense as I read it as “this is the browser-environment file for this path.”

So if the conditions describe the target files, and I remember the array syntax this time, my example above could be better written as:

{
  "type": "module",
  "main": "./index.cjs",
  "exports": [{
    "commonjs": "./index.cjs"
  }, {
    "module": "./index.js"
  }]
}

In this case, both Node loaders will load index.cjs, as both support "commonjs"-type files and that’s defined first in the array, making it top priority.

If the conditions instead describe the loader/method of importation, then I would call them require and import to make that connection clear. But then in order to achieve the same desired result (both Node loaders get CommonJS, other runtimes get ESM) you’d have to write as:

  "exports": {
    "node": {
      "require": "./index.cjs",
      "import": "./index.cjs"
    },
    "import": "./index.js"
  }

This feels counterintuitive to me, like it’s configuration for Node rather than metadata describing the package. Wouldn’t this also potentially introduce issues if the capabilities of loaders change over time?