← sz3yan.com

#szejo ·

>=20.9.0 is a floor, and floors don't stop you falling upward

A brand-new Node release broke npm install on a project whose engines field swore it only needed =20.9.0 . The failure was a native addon refusing to compile — six C++ errors against V8 headers that…

1 min read

A brand-new Node release broke npm install on a project whose engines field swore it only needed >=20.9.0.

The failure was a native addon refusing to compile — six C++ errors against V8 headers that had deprecated the APIs it used. Every Node on the machine was the same too-new version, and there was no version manager installed to switch away from it.

The real constraint was a V8 ABI ceiling that nobody writes down. engines declares a floor and says nothing about the top. The only place the supported version actually existed was the project's own Dockerfile, which pins a major version the host toolchain never reads.

The fix needed no version manager and no dependency bump: run the dev server in the container the project already ships, with the repo bind-mounted for hot reload and node_modules on a named volume so the Linux build never lands in the host checkout.

Lesson. A manifest declares what a project asks for; the Dockerfile declares what it was actually tested against. When those disagree, believe the one that builds.