Module resolution: ESM vs CJS

[sheerlox]

Module resolution in JavaScript is a complex topic.
The ecosystem is currently in the midst of a years-long transition from CommonJS modules to native ES modules.
Bun - Module resolution documentation

You might want to read more about the differences between CJS and ESM before reading/replying to this discussion.

---

So .. I've been doing research in the past few hours regarding the best way to support both CJS & ESM exports, which seems pretty simple to implement, but creates an issue called the dual package hazard (as well as increasing package size since we effectively ship the library two times).

Another solution is to support only CJS, which ESM is able to load (this is what we are currently doing).

Over the past few months, I've been redirected to this gist a few times by some libraries I was using, that chose to switch to pure ESM modules. They still support CJS with the previous major version being maintained, but new features are only available on the pure ESM version. Personally, this is a stance I appreciate, as it is a strong statement that pushes the whole JavaScript ecosystem forward.

According to this analysis, ~ 10% of npm high-impact packages are currently pure ESM modules (which means they can only be used by other pure ESM modules).

From what I could read across the resources I linked, ESM seems to be a much better choice for the future (it was created to supersede CJS after all), mainly because it introduces a standard that is supported in both server-side and browser environments and allows for asynchronous loading. All the information I encountered would lead me to push forward for a pure ESM migration since we are releasing V3, but I still have some reservations about it:

A big issue concerning cron when considering switching to a pure ESM module is that Nest and especially @nestjs/schedule are compiled to CJS, which means the latter won't be able to upgrade to V3. This library is our biggest downloads source to date, so we might want to postpone migrating to pure ESM in a future major version.

Based on the information I presented above, and what I could make of the details found in the resources below, I suggest we keep the library in the state it's in (CJS) for now, since that can still be imported in ESM (and in Deno thanks to the Node.js Compatibility work that's been done, initially it didn't support CJS module loading, see the deno branch on my cron test repo for Deno code working perfectly with v3.0.0-beta.8).

Resources

• https://redfin.engineering/node-modules-at-war-why-commonjs-and-es-modules-cant-get-along-9617135eeca1
• https://www.typescriptlang.org/docs/handbook/esm-node.html
• https://devclass.com/2023/07/05/commonjs-here-to-stay-or-gone-tomorrow/
• https://deno.com/blog/commonjs-is-hurting-javascript
• https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
• https://nodejs.org/api/packages.html#dual-package-hazard
• https://webreflection.medium.com/cjs-vs-esm-5f8b90a4511a
• https://github.com/wooorm/npm-esm-vs-cjs

[intcreator]

I agree we should wait on ESM until at least v4.0 and possibly even until Nest JS makes the change. since this is a small library that can be imported in all sorts of projects it will be nice to have that compatibility for a while, at least until a really compelling advantage to ESM emerges that causes most projects to move over. right now it's fun to use ESM and looks a little cleaner but still feels like a new methodology rather than the standard