Badge on NPM packages to show support for ESM entry point

[jonkoops]

Now that ECMAScript modules are widely supported in the NodeJS and JavaScript ecosystem I find myself more often looking explicitly for modern packages that support these modules out of the box. Currently if I look around the NPM site I have trouble to find the right package, as I would first have to dive into the source code of the package to understand if it actually supports ESM.

I'd love to see a badge, just like the one that indicates that a package has type definitions available to indicate support (see mockup below). This way I can instantly see if the package supports ESM.

Detecting this would work in a similar manner as the TypeScript badge, by analyzing the contents of the package.json file.

[ljharb]

Why do you find yourself doing that? node ESM, and transpiled ESM, can import CJS modules just fine; there’s nothing “not modern” about those.

in other words, every CJS package supports ESM.

[jonkoops]

right, but "a CJS file" is an entry point that supports ECMAScript modules, because you can import them (which is the only definition of "support" that i think anyone should care about).

Again, in the NodeJS ecosystem this might be true, but outside this is not always the case. For example:

• Webpack cannot tree-shake CommonJS modules
• Rollup cannot bundle CommonJS without a plugin
• Browsers don't understand CommonJS modules
• Deno does not support CommonJS modules

[jonkoops]

I don't think the proposed implementation in any way suggests that browsers could directly run a package that uses ESM (although a lot less transformation and logic would be necessary than with CommonJS).

This is simply about whether a package (and not even it's dependencies) exposes an entry point to an ESM module. Which can be relevant for those who are not using a NodeJS environment.

[ljharb]

Right - but that will create a perverse incentive for packages to unnecessarily add an ESM entry point that re-exports their existing CJS implementation.

I could understand two badges - “can be required” or “can be imported” - and most packages will have both, but ESM-only packages will have just one, and C++ packages will have just one.

[jonkoops]

That's a valid concern. I am sure there are those out there that might be using tooling that can only deal with CommonJS, and don't want to accidentally install an ESM version.

I agree that adding both a badge for CommonJS and ESM to give people a transparent picture is the better option 👍

[ljharb]

To be clear, I’m suggesting a badge for “requireable” and “importable”. The module format shouldn’t matter, and won’t actually give you the property you want, and is very difficult for npm to determine.

[rauschma]

I like how Skypack handles this – e.g. (details on the right): https://www.skypack.dev/view/preact

[jonkoops]

I love how Skypack shows their package score, it is really helps understand the quality in a clear overview. I've always found it very hard to understand the seemingly arbitrary 'Quality' score on the NPM site.

[rauschma]

I don’t like the score itself (impossible to condense this into a single number), but the feature list is nice.

[jonkoops]

Yes, I like the transparency that the list provides. The quality here is relative to what you need as a consumer, but in the case of Skypack it reflects what makes it easier to provide their service.

[Westbrook]

@jonkoops really interesting request, could definitely see it being useful in a lot of contexts. Wonder if you'd share some additional information about your usage on "supports ES Modules" as "modern". Using JS with CJS modules in a node environment, wouldn't a project be able to get the "modern" label just as easily as if it were shipped as ES Modules based on that actual JS that it contained? I definitely have personal feeling in support of ES Modules as a whole, and am interested in your thoughts on whether a JS library could be "modern" without them.

What's more, I ask, because I see "has ES Modules" as only half the story of a bigger request in my work, and that's "is browser ready". This takes into account things like CJS modules or process.env and others not working in the browser by default and thus requiring build tools to leverage in that context. Some other commenters point to the very correct point that any number of tooling situations could bridge that gap between Node first dependency and browser capable dependencies. However, a clear indicator that you could forego the hard part of setting up advanced tooling while getting into a new project as indicated by NPM could do wonders for how new developers got started in the craft.

With that in mind, I'd much rather see NPM take the next step in its evolution from Node (only) Package Manger to de facto JS, or even everything, Package Manager and more clearly define the contexts where in a listed package can be used. "Is browser ready" might not even be the only context for that, especially as more and more tools make it into NPM. It might make sense to start clarifying more and more of these contexts (wasm, node, CSS, there was talk of C++ above) so that NPM could support getting users to success even faster than ever.

I look forward to more on your thoughts here, and strongly agree that NPM is in a great place to leverage its outsized and growing influence in this area to support a demystification of the ecosystem on any number of axes... +1!

[Seanmclem]

For me it's Deno. I love how quickly and easily I can use any esm package and like to avoid the added difficulty of not using them

[jonkoops]

Wonder if you'd share some additional information about your usage on "supports ES Modules" as "modern".

I definitely have personal feeling in support of ES Modules as a whole, and am interested in your thoughts on whether a JS library could be "modern" without them.

So I think it's important here to note that I only consider it to be "modern" because it is a newer standard. However whether this is suitable for your needs is entirely up to the tooling you use.

Using JS with CJS modules in a node environment, wouldn't a project be able to get the "modern" label just as easily as if it were shipped as ES Modules based on that actual JS that it contained?

I don't quite understand what you are asking here, could you elaborate?

What's more, I ask, because I see "has ES Modules" as only half the story of a bigger request in my work, and that's "is browser ready".

This is true, just because a module is written in ESM does not mean that it cannot be used inside of the browser. Some assumptions that exist in Node (like importing a package by it's name) simply do not (yet) exist in the browser. Having ESM in a package does however allow tooling to further optimize it when building, which is essentially why I would want this 'ESM' badge.

Perhaps the browser field can be used with conditional exports to accomplish this.

[ljharb]

No, it doesn’t; there’s nothing about ESM that’s more optimizeable than CJS - it’s just that a number of tools don’t bother to implement the same optimizations for CJS modules.

[jonkoops]

No, it doesn’t; there’s nothing about ESM that’s more optimizeable than CJS

CommonJS is not completely statically analyzable due to the fact it it operates at runtime, this is a fact. Some tools depend on this to optimize code beyond what CommonJS can accommodate.

[ljharb]

@jonkoops both CJS and ESM have static and dynamic forms. It is a fact that they are identical in this way - dynamic import for ESM, and require with “not a string literal” for CJS, are both impossible to analyze; static import for ESM and require with a string literal are both identically static.

[mhdawson]

I’m suggesting a badge for “requireable” and “importable”

This makes sense to me.

[kito99]

We really need something like this. If someone is looking for an ES module, right now it's way too much work to determine if it's supported, especially for someone new to the ecosystem.

[MylesBorins]

There's a historic discussion about identifying a number of format details of a package, does it make sense to folks this conversation into there?

https://github.com/npm/feedback/discussions/13

[jonkoops]

@MylesBorins is there a way to actually progress this issue? I'd love to contribute something to the NPM site, but considering the fact that AFAIK it's closed source, there seems to be very little the community can do to enhance the experience there. Not just talking about this specific issue, but also various other enhancements.

[ljharb]

Indeed, as @justinfagnani mentions, the actual question that matters to users is "can i use this package in my app?"

The module format may or may not matter; whether it works in browsers and/or servers may or may not matter; how large it is may or may not matter; how many deps it has may or may not matter.

"Perfect is the enemy of the good" doesn't handwave away that only talking about module formats isn't good - it's just not useful information by itself, and it's more likely to be harmful (ie, perverse incentives) than helpful.

[jonkoops]

"Perfect is the enemy of the good" doesn't handwave away that only talking about module formats isn't good - it's just not useful information by itself, and it's more likely to be harmful (ie, perverse incentives) than helpful.

@ljharb we fundamentally disagree on this, and I don't think we will or have to settle our differences here. It might not matter to you, but that doesn't mean it doesn't matter to others. I think that is pretty evident from this being the second most upvoted discussion, and from other reaching out here to discuss this feature request.

Not talking about a problem because you don't want it to exist in the larger ecosystem outside of Node.js isn't going to make the problem go away. All I am asking for here is the information that might be relevant in making such a choice is presented to the user. so they can make a judgement themselves.

[jogibear9988]

I've found so much packages, wich for example have a ESM entry point, but their internal imports do not have file extensions, so the package does not work without using a bundler.
I try this for example most of the time in my web-component-designer, wich could load directly npm packages. Nearly for every package I try I need to create bug reports or fixes, cause the package itself or some of it's dependecies has errors in the ESM exports.

[justinfagnani]

I've found so much packages, wich for example have a ESM entry point, but their internal imports do not have file extensions, so the package does not work without using a bundler.

At least those will work with import maps or a simpler transform that only resolves import specifiers.

But it does raise an important and subtle point: It may be obvious to many that using npm packages names requires an import map or transform for any module that imports an npm dependency. It may be less obvious that using non-relative paths (including paths without extensions) internally requires an import map or transform as well. And it may be even less obvious that even though both cases require an import map or transform, needing import map entries for internal specifiers can drastically blow up the size of the import maps compared to just needing 1 or 2 entries per package.

So when determining whether a package is "web ready", it matters what requirements are made of the specifiers, ranging from only being valid URLs or relative paths (not practical, IMO); to allowing bare specifiers for package names, but otherwise having paths that don't require further resolution (practical and optimal for import maps, IMO, but commonly violated), to allowing any specifier that can be resolved by Node resolve (pretty much rules out import maps).

I suspect there would be a fair amount of disagreement about which specifier requirement would make it into a "web ready" designation.

[jogibear9988]

I've found so much packages, wich for example have a ESM entry point, but their internal imports do not have file extensions, so the package does not work without using a bundler.

At least those will work with import maps or a simpler transform that only resolves import specifiers.

Yeah for sure, but I could only create them automatically when the package.json has a "exports" section (wich most of them do not have atm.) where these all are listed. If not, it may be possible for a bundler or other local app wich parses the files and searches for the imports, but not for my lib wich only loads the npm's (the other also would be to slow to do live)

[jonkoops]

@jogibear9988 probably best to reply in-thread, rather than starting a new one, otherwise this discussion will become very disconnected.

[jogibear9988]

yeah, was an accident