Skip to content

Require Node 24 and npm 11 - #58

Open
hupponen wants to merge 1 commit into
masterfrom
require-node-24
Open

Require Node 24 and npm 11#58
hupponen wants to merge 1 commit into
masterfrom
require-node-24

Conversation

@hupponen

Copy link
Copy Markdown
Contributor

npm versions resolve optional peer dependencies differently, which makes package-lock.json depend on the npm version that wrote it.

A concrete case: vite 8.2.2 has esbuild as an optional peer dependency. npm 11 leaves optional peers out of the lockfile, npm 10 installs them. A lockfile written by npm 11 therefore makes npm ci fail on npm 10 with Missing: esbuild@0.28.2 from lock file and 26 similar lines for its platform packages. Regenerating with npm 10 fixes that machine, but then the next npm install on npm 11 removes those 512 lines again, so the lockfile keeps flipping back and forth. This has happened before, see 86f04bb "Regenerate package-lock.json with npm 11.14.0".

The dev container and the production images use Node 24, which comes with npm 11, so declare that as the requirement instead of leaving it to whatever each developer happens to have installed.

Changes

  • engines in package.json: node >= 24, npm >= 11
  • .npmrc with engine-strict=true, because npm only warns by default and the resulting lockfile error is confusing to debug

Testing

  • npm ci on Node 24.20.0 with npm 11.19.0: installs normally
  • With engines.node temporarily set to >=99, npm ci fails as intended:
npm error code EBADENGINE
npm error notsup Required: {"node":">=99","npm":">=11"}
npm error notsup Actual:   {"node":"v24.20.0","npm":"11.19.0"}
  • npm run build: production bundle builds

Anyone on an older Node now gets a clear error instead of a lockfile mismatch. Switching Node versions is easiest with nvm or asdf.

@hupponen
hupponen requested a review from klemela August 28, 2026 19:51
Older npm versions install optional peer dependencies that npm 11 leaves
out, so they produce a package-lock.json that npm ci rejects on the other
version. The dev container and the production images use Node 24, which
comes with npm 11.

engine-strict in .npmrc turns the version check into an error, because a
warning is easy to miss and the lockfile error it leads to is confusing.
.nvmrc lets nvm and similar tools select the right version in the first
place, so that check does not have to be the thing that fails.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant