[RRFC] Populate `"engines"` field during `npm init`

[valadaptive]

Motivation ("The Why")

When packages do not specify a minimum supported Node version, some people may assume that the package supports any version of Node--or at least the ones that their currently-installed version does not error out on.

This can lead to semver hazards--a maintainer may inadvertently use a JavaScript builtin (as old as Array#map or as new as Object.hasOwn) or a Node standard library feature that is not supported across all versions of Node. This could be seen as a breaking change, and hence semver-major, but it is very hard for the maintainer to notice.

In order to use features that are not supported across all releases of Node in a semver-compatible way, authors must include the "engines" field in their package.json. Currently, however, few do so--probably because it is not included by default.

Example

See current semver hazard examples:

• https://github.com/indutny/elliptic/issues/314
• https://github.com/dequelabs/axe-core/issues/4127

How

Current Behaviour

npm init does not currently specify any minimum supported Node version.

Desired Behaviour

npm init should specify a reasonably recent Node version as the minimum supported one in the "engines" field, for some definition of "reasonably recent". The exact timeframe can be bikeshed over, but here are some ideas:

• The version of Node released some number of years ago (this can be longer than the EOL timeframe, since people are sometimes slow to upgrade Node--but do we want to encourage that?)
• The earliest LTS non-EOL version of Node
• The latest LTS EOL version of Node

Unanswered Questions / Further Work?

• Does npm currently provide a warning when you depend on a package whose minimum Node version is higher than the one you specify? Could it?
• Since the engines field consists of machine-readable semver, should the NPM registry require an engines bump to require a new major version number?
• Other runtimes, like bun and deno, now exist as well. An argument could be made that since those engines are likewise not mentioned in package.json, all of their versions must be supported. While their Node compatibility is still work-in-progress and not officially stable (AFAIK), there may come a time when they do reach parity with Node.
  • Should maintainers be required to keep up-to-date with all third-party runtimes and e.g. include "bun" and "deno" fields within "engines"? I see this as untenable, both because it is a lot to ask of maintainers and because npm would need an "official" list of all third-party runtimes.
  • They are the ones implementing APIs that Node is responsible for designing, so should it be their responsibility to map Node versions to the corresponding versions of their own runtimes?
  • ECMAScript features are another matter entirely. Third-party runtimes could support different subsets of new ECMAScript features from Node. Should they, again, be asked to map Node versions onto versions of their own runtime? Should a cross-runtime "JS support level" field be designed?

[markcellus]

I havent used npm init in quite some time, but sounds like a feature that could help.

Only downside is that it requires the maintainer to actually know what versions are incompatible, which may be difficult. Incompatibility isn't always easy to determine based on syntax alone, so I'd doubt this could be 100% automated in a reliable way.

It's one of the reasons why on some projects I assume all node versions are compatible and only really update engines to exclude a version (and anything below it) when I know for sure a version is incompatible. Usually I verify incompatibility by either manual testing or as a result of bug reports 😀

[valadaptive]

It's one of the reasons why on some projects I assume all node versions are compatible and only really update engines to exclude a version (and anything below it) when I know for sure a version is incompatible. Usually I verify incompatibility by either manual testing or as a result of bug reports 😀

Right; the issue is that updating engines is a breaking change to some people. The idea behind automatically setting a recent engine is that people would be able to follow modern coding practices without having to worry about compat bugs. Even something like let/const is not supported in all versions of Node.

[ljharb]

It’s a breaking change per semver.

This is actually a really great idea, as long as there’s no default and a few examples are given in the prompt.

As for warnings and checking compliance, that’s what i made npx ls-engines for. I’d love to see that functionality built into npm.