Migrate source code to ESM?

[zanminkian]

Node is defaultly supporting require('esm-module'). ESM is the future.

Moreover, pure js project under ESM would be more easy to add type annotation to improve type-safety.

That means commander will not provide CJS distribution in npm package.

Feel free to close it if not planned.

[shadowspawn]

I am interested in whether there are benefits in switching to esm-only.

Moreover, pure js project under ESM would be more easy to add type annotation to improve type-safety.

I am not sure what you mean here. Can you give an example?

[stefnotch]

@shadowspawn
There is this post which covers the most important points of why more and more authors are switching to esm only https://antfu.me/posts/move-on-to-esm-only

[shadowspawn]

Thanks @stefnotch, I had seen that article and read it again.

[shadowspawn]

Lots of notes.

I am excited about ESM becoming more practical to adopt for both leaf projects and libraries with node now supporting require(esm), and reducing the expectations and extra work for libraries to support both CJS and ESM.

From the consumer point of view, Commander transparently supports ESM. There have not been many reports of problems with the CJS implementation, but there was one reported with an esm-only bundling tool (#1781). This might come up more in the future as more tooling moves to esm-only.

From the maintainer point of view, we ship a relatively low-overhead dual package implemented in CJS. There is a very small esm shim: https://github.com/tj/commander.js/blob/master/esm.mjs. We don't do a transpilation step for full dual native CJS/ESM.

The support for correct TypeScript definition support for dual CJS/ESM was a pain! (#1880) That was something I could have done without.

Node.js are reviewing their own documentation and guidance around packaging, and I'll be watching that space: https://github.com/nodejs/package-examples

At the moment I am interested in esm-only, but don't see enough benefits to make the move soon.

[stefnotch]

Glad I could point you in a useful direction!

So I suppose the answer to the issue is: The migration will happen, but only once there's a pressing need, or if enough users politely request it.
Is that an accurate summary?

[shadowspawn]

My summary: the migration will happen when there are sufficient benefits, or is likely to happen anyway when there are less downsides. (The maintainers like moving forward with modern Javascript.)

As a concrete example, if we went esm-only next month when node 18 goes EOL, any CJS users on an LTS version of node 20 (active LTS start 2023-10-24) lower than 20.19.0 would need to upgrade node to 20.19.0 to update Commander. I consider that a downside.

if enough users politely request it

It is more about why users are requesting it. What are the benefits to them, either as end-users of Commander or as code contributors to Commander?

How would you benefit by Commander going esm-only now?

From the article The Troubles with Dual Formats, I don't see sufficient benefits at the moment:

• Interop Issues: only 1 known issue for end-users with a work-around (Rollup bundle error with Typescript #1781), and no current work for maintainers
• Dependency Resolution: Commander has no production dependencies
• Package Size: tiny shim, negligible impact

[shadowspawn]

(We already removed the default export in #2017 so don't need to change that when we go esm-only.)

[ericmorand]

@zanminkian

That means commander will not provide CJS distribution in npm package.

Not sure why this would be required. commander could totally - and should - emit both flavors. It is trivial to do, once of course the source code is migrated to ESM.

[ericmorand]

@shadowspawn

How would you benefit by Commander going esm-only now?

We have to add commonJS plugins to our bundler confgurations only for commander - and tape for test bundles but that's another story. This is not a big downside, obviously, but it would make our bundles easier to produce and a little bit smaller.

[shadowspawn]

Thanks for the commonJS plugins example @ericmorand

[shadowspawn]

That means commander will not provide CJS distribution in npm package.

Not sure why this would be required. commander could totally - and should - emit both flavors.

Why "should"? Apart from for people using older versions of node that don't support require(esm).

I see a big part of the attraction of esm-only for library maintainers is less configuration and build steps to maintain. We do not currently ship two native flavours, and do not need a transpilation step in Commander. I am expecting we go to esm-only and not go to dual native flavours.

[shadowspawn]

A couple of interesting blogs from the primary author of require(esm), Joyee Cheung, on the journey:

• https://joyeecheung.github.io/blog/2025/12/30/require-esm-in-node-js-from-experiment-to-stability/
• https://joyeecheung.github.io/blog/2025/12/30/require-esm-in-node-js-implementers-tales/

[shadowspawn]

The Node.js documentation for migrating from CommonJS to ESM has recently been released:

• https://nodejs.github.io/package-examples/05-cjs-esm-migration/