Make it easier to identify the format of a package

[MylesBorins]

Problem Statement

While individuals can use keywords to help sort / identify a package it is not an exact or reliable way of identifying the format of a package or the runtime it is expected to be executed in. I've heard feedback from those new to the JavaScript ecosystem that sometimes it can be very hard to know where they can run something once they've npm install'd it.

Some example identification includes:

• browser
• node
• tooling specific plugin
  • eslint
  • webpack
  • rollup
• TypeScript
• Framework specific extension
  • Angular
  • React
  • Vue
  • Express

Potential Solutions

There are a couple of different ways this could be solved on the backend ranging from static analysis of the source text to examining fields in the package.json including package.exports, package.module, and package.main.

As a consumer of packages it would be nice to have a way of surfacing these details in both the cli and the website. This information could also be useful when searching for modules.

[wesleytodd]

@Ethan-Arrowood have you seen this? npm/rfcs#126

[Ethan-Arrowood]

No I haven't, thank you for sharing!

[developit]

As a first step, it would be great to surface descriptive information about a package's exports in the npm website's sidebar. Rather than listing permutations of entry points and mainFields, something higher-level:

What's inside this package?
𐂷 multiple entries (hooks, compat, +3)
🜸 ES Modules, CommonJS, UMD
☆ ES2015 syntax, dynamic imports

The "ES Modules" criteria could be that all non-bare import specifiers are directly resolvable to filepaths. That would help drive folks to using ESM as-specified, rather than "transpile-only" or "bundler-only" ESM with intermixed CommonJS semantics.

[MylesBorins]

For the ESModule verification, are you imagining that npm would statically analyze the entire tree from the entry point to verify validity? Would you consider specifier behavior that could be handled via package.exports or import maps to be in scope? or only modules that don't require any tooling?

[bmeck]

What would be the behavior for packages that have multiple entry points?
What is the intent for non-standard syntax here?

{
  "exports": {
    "": "", // only CJS?
    "a": {
      "jsx": "./a.jsx", // JSX?
      "require": "./a.cjs", // CJS
      "import": "./a.mjs" // ESM
    },
    "b": {
      "ejs": "./b.ejs", // EJS?
      "require": "./b.cjs", // CJS
      "import": "./b.mjs" // ESM
    }
  }
}

I'd presume it is a sum of some sorts.

[MylesBorins]

I think a sum makes sense. Let folks know what interfaces are available.

[ljharb]

(continuing from npm/feedback#634)

What about providing a badge for "requireable" and "importable"? "main" and/or "exports" can indicate whether a package is requireable and/or importable. Any ESM-only package would be only importable, any CJS-only or dual package would be both, a package with C++ entry points would be only requireable, any package that has no entry points would be neither.

That would map neatly to what node supports, and what bundlers expect.

[rauschma]

Use case I’m having right now: For testing, I’m using an ESM loader hook to replace the built-in fs implementation with one that handles files in RAM. That means I can only use ESM libraries.

Thus, I think both is useful information:

1. I sometimes want to know (for various reasons!): Is there an ESM inside this package?
2. Often, “can I import this from ESM?” is enough.

In a way, these are different degrees of ESM support.

[ljharb]

I'm not sure why it would - an ESM loader can instrument require.cache or mutate builtins.

[rauschma]

What can you not import from ESM?

I can import CJS-based libraries, but they are not affected by the ESM loader hooks.

By (2), I mean your idea for an “importable” badge.

[rauschma]

I'm not sure why it would - an ESM loader can instrument require.cache or mutate builtins.

I get your point: You want to avoid inexperienced users misjudging libraries. All I am saying: I occasionally find it useful to know whether a library is ESM or not.

[wesleytodd]

Knowing which types of exports it exposes (ESM/CJS/DUAL) seems separate from the loader thing to me. So just to be clear, you can do the same thing with either CJS or ESM via loaders. So if you are an ESM consumer you can import code from any of the three configurations. It is only if you are a CJS consumer that a lib which publishes only ESM is a problem. Would it maybe be better to flag "ESM ONLY" as that is really the broken configuration today?

[ljharb]

Exactly that.

As for a loader author, if you author your loader to handle all file formats node supports, then you shouldn't need to know what format a specific package is - it's either requireable, or not, and importable, or not.