Should I specify the node version in pnpm-workspace or package.json?

[mikem-of]

I see multiple ways of specifying the nodejs version in pnpm 11:

• pnpm-workspace.yaml has a nodeVersion field
• package.json has a devEngines.runtime field

It's not clear for me which one to use.

pnpm itself uses both fields with completely different node versions:

• https://github.com/pnpm/pnpm/blob/main/pnpm-workspace.yaml#L398 (node 22)
• https://github.com/pnpm/pnpm/blob/main/package.json#L73 (node 26)

Can someone explain the difference? And maybe the docs can be a bit more clear on this?

Thanks!

[sueun-dev]

They're two different knobs, and pnpm's own repo is actually a decent illustration of the split.

nodeVersion in pnpm-workspace.yaml only sets the version pnpm assumes when checking engines ranges, it never changes what actually runs. On pnpm 11.5.3 with real Node 22.22.3, setting nodeVersion: 22.13.0 plus engineStrict: true failed an engines.node: ">=22.20.0" check with "Got: 22.13.0". So 22.13.0 is just the floor the repo validates dependency compatibility against.

devEngines.runtime declares the Node devs actually use, and pnpm enforces it: with "version": "26.3.0", "onFail": "error" install refused to run on 22, and with "onFail": "download" pnpm fetched 26.3.0 and pnpm node -v printed v26.3.0. There's also #9817 where zkochan says to prefer devEngines.runtime since it's the new standard field, so for your own project that's the one to set.