Proposal for dual ESM/CommonJS packages

[GeoffreyBooth]

@guybedford, @jkrems and I discussed the package dual-ESM/CommonJS case and we have a small proposal, based on the current ecmascript-modules implementation:

• The package.json "main" field reverts to its prior CommonJS-only use.

• A new field "exports" is created that takes a string like "./src/index.js". This is the ES module entry point. "exports" is to import what "main" is to require.

Notes:

• "exports" may in the future take an object, preserving design space for the package exports proposal.

• If "exports" points to a .js file and "type": "module" is not set, an error is thrown similar to the “type mismatch” errors (like using --type=commonjs with an .mjs file). The error would also instruct the user to add "type": "module" to package.json. The "exports" field does not imply "type": "module".

And that’s it! This should cover the case while preserving design space for future proposals, and for Node potentially switching to ESM by default someday.

[devsnek]

this still feels like esm is second-class. allowing extension searching gets rid of the entire dual mode issue.

[ljharb]

I would prefer not to proceed with "exports" until we have extension lookup, at which point the easy way to get dual-mode packages will be foo.js and foo.mjs, where "main" is foo

[GeoffreyBooth]

There’s nothing about the proposal above the prevents extension searching from happening, either opt-in or by default. This proposal need not be tied to that, and I think it’s better if it isn’t. Keep in mind that package.json isn’t only for Node’s use; build tools and other platforms will need to be able to read it, and it’s a burden on them if we force them to implement Node’s extension searching algorithm in order to determine the ESM entry point. Even if we allow automatic extension searching within the Node runtime itself, for compatibility with other tools and environments it would be better if it doesn’t extend to package.json.

[devsnek]

@GeoffreyBooth whether exports exists or not, they have to do searching for the main field. why not just keep it simple.

[GeoffreyBooth]

@devsnek Tools need only do extension lookup on main to support CommonJS, which will become increasingly uncommon as it's a Node-only thing.

[hybrist]

way to get dual-mode packages will be foo.js and foo.mjs, where "main" is foo

This seems to imply that you'd have to have both in the same directory which is really uncommon. This doesn't fit well with either compilation-to-CJS or "esm interface in root, source in lib". It would mean more empty junk files in package roots unless I'm missing something about this suggestion.

[zenparsing]

@GeoffreyBooth You did great work anayzing packages with a "module" key. I'm curious if we've done any similar analysis of previous usage of the "exports" key. Does it conflict with any existing ecosystem usage? (Apologies if this belongs in another thread.)

[GeoffreyBooth]

@zenparsing I looked it up, and it's been a while so I don't remember the usage number offhand but basically we can claim exports. It's either completely unused or used by only a handful of public npm packages.

[MylesBorins]

@GeoffreyBooth I believe that the last time package.exports came up the feature was discussed as something that might be useful for common.js as well. It seems like this proposal is making the assumption that the only things to be exposed by package.exports would be ESM. It seems a bit fragile if we would eventually want to support ESM, alternatively it also seems like it may fail as we introduce more goals e.g. wasm / json / etc

[devsnek]

@jkrems both ways leave a patterns of doing things out. assuming i'm not unique on this planet, this proposal is more junk for some people's package.json, but less junk for people who have a src and lib directory. personally i tend to prefer solutions for people that don't use build tooling since build tooling can automagically fill configurations in and whatnot. i think this is definitely something worth discussing more in call.

[GeoffreyBooth]

@MylesBorins This proposes that the shorthand string value be the ESM entry point, but the verbose object form could define CommonJS values as well. That’s why exports on its own doesn’t imply "type": "module".