build: enforce node version requirement clearly when running npm install

[nbogie]

Increasing Access

When developers run the website server or scripts on an unsupported (e.g. too-old) version of node.js they can encounter cryptic, seemingly unrelated problems in the code-base which can waste a lot of their time and be an off-putting developer experience especially for newcomers.

In contrast a system that clearly communicates to them with an error state that their platform is incorrect, allows them to move forward without confusion, saving time and ensuring a more reliable (and welcoming) developer experience.

Most appropriate sub-area of p5.js?

Other (specify if possible)

Feature request details

Running npm install (or npm ci) should fail with a clear descriptive error if an unsupported version of node.js is being used. The error should state that the version of node.js is unsupported by the software and state what version(s) of node.js ARE acceptable.

An error, not a warning:

A warning is insufficient as it will very easily be missed in the noisy logs. Instead, the process should stop with the error being the last thing reported, and the process exit code should be non-zero to allow use in automated setups.

Support the widest user-base

The solution (i.e. the detection and error mechanism) should work for the widest possible range of developer setups. For example, whilst specifying devEngines in package.json will eventually be a solution, at the moment there will still be developers who are using old systems which will ignore this new specification.

Similarly, we cannot assume that all developers are using volta, nvm, or fnm.

"Why the install command, why not point X?"

The website system consists of many entry points. Rather than try to cater for all of them, it is simpler and more reliable to address just once the central point that all developer workflows should be including periodically, npm install.

Other package managers:

While ideally the same solution would work with yarn and pnpm, this is not required and we should not add extra files to support those tools.

Support for CI

It'll be necessary to check that these checks don't break current CI (testing and deployment).

I suggest CI enforcement of the node version requirement can be implemented later.

If, in the solution for the non-CI case, the declaration of supported node version(s) can be read easily by CI, it will allow all systems to eventually run from a single source of truth.

Consistency with p5.js main library

If possible, it would provide a simpler developer experience if node version requirements for p5.js-website and p5.js development can be the same.

Documentation

The prerequisites section in contributor guidelines should be updated to state the acceptable node.js version range.

Potentially, a pointer could also be added there so that the developer knows where to look for the up-to-date accepted version range.

Which version of node.js should be the minimum?

Either at least v22 or at least v24.

Version 24 is the active LTS (long-term support) version. However, specifying that version would create a larger disruption than specifying version 22, as more developers will have to change node version at that moment, and those not using a version manager (such as nvm) would be faced with an immediate problem if they also need to another version of node in another project.

We could instead require v22 which is supported until april 2027, and then update in 6-12 months to move that requirement to v24. Of the two possibilities, this gives developers more flexibility.

The node.js release schedule shows which versions will be supported through which time periods. https://nodejs.org/en/about/previous-releases#release-schedule

Expecting and handling the disruption

Once released, a system that enforces the node version requirement will cause some immediate disturbance for developers.
Provided the error message is clear, this disturbance should be easily remedied for most.

However, some developers will need to learn for the first time how to do so. So, we might accompany the release with:

• a small note
• a pointer to guide(s) on how to update version (e.g. for nvm),
• a light recommendation to use nvm (or similar)
• details of a temporary workaround for those who can't immediately update their node version. (As an example, that might be removing engine-strict=true from .npmrc if we decide to use that mechanism)

Testing

The system should be tested on at least windows, mac, linux

Initial conversation on discord

This includes some suggested implementation details.
https://discord.com/channels/836700474425475088/1481664886827257977

[nbogie]

My suggestion:

For now, we can stipulate a minimum node version in engines in package.json

"engines": {
    "node": ">=22.0.0"
  },

...and force npm to fail if this isn't met, by adding a file .npmrc stipulating engine-strict

Entire file contents would be:

engine-strict=true

[nbogie]

I'd like to work on this.