pnpm.executionEnv.nodeVersion vs engines.runtime

[markedwards]

As of pnpm 10.21.0, is pnpm.executionEnv.nodeVersion deprecated? And if so what is the correct way to specify the node version for the root workspace? The engines.runtime declaration does not seem to do it.

[zkochan]

What is the issue?

This works for me in package.json:

  "engines": {
    "runtime": {
      "name": "node",
      "version": "23",
      "onFail": "download"
    }
  }

[markedwards]

Got it. The thing is, I want to be able to do this in the following Next.js app scenario:

1. pnpm install
2. run steps to build the Next.js app in "standalone" mode which will create an optimized node_modules along with a copy of the minimal file structure, including the necessary package.json
3. package the standalone file structure into a Docker container with pnpm installed
4. pre-populate node in the Docker container
5. deploy to production, using pnpm node server.js to run the app

So I do not want to have to do a pnpm install at step 4, because that will defeat the purpose of already having installed, built, and packaged the dependencies. Using pnpm.executionEnv.nodeVersion this was working well, as I could run pnpm node --version in order to ensure node was downloaded into the Docker image.

The reason to do this instead of installing Node in the Dockerfile separately is to ensure consistency with the Node version that is run in dev and prod and CI, etc.

Can this be achieved with engines.runtime? If not, will pnpm.executionEnv.nodeVersion continue to be supported or is it going away? Is there a better way to think about achieving the goal?

[markedwards]

Update here -- we will actually eliminate usage of Next standalone builds, but for a different set of reasons.

So I think I have no remaining issue here. But just to close this -- is pnpm.executionEnv deprecated and no longer safe to use? Will it still be supported?

[zkochan]

In your scenario, can't you just install node.js globally? Via pnpm env use -g <node_version>?

So I think I have no remaining issue here. But just to close this -- is pnpm.executionEnv deprecated and no longer safe to use? Will it still be supported?

Yes, I think we will deprecate it. I don't want to support two systems that do the same.

[markedwards]

In your scenario, can't you just install node.js globally? Via pnpm env use -g <node_version>?

So I think I have no remaining issue here. But just to close this -- is pnpm.executionEnv deprecated and no longer safe to use? Will it still be supported?

Yes, I think we will deprecate it. I don't want to support two systems that do the same.

No, this is a monorepo with different node versions for different workspaces. So this is a specific node version for this workspace.

But it any case the engines.runtime approach actually works fine for us.

[zkochan]

There might be a workaround. Like you could easily install two node.js versions globally. So they'd be precached.

[markedwards]

Separate question -- after adding this:

  "engines": {
    "runtime": {
      "name": "node",
      "version": "24.11.1",
      "onFail": "download"
    }
  },

pnpm wants to add "node": "runtime:24.11.1" to dependencies whenever pnpm add is used to add anything. Is this expected? Should node be added to dependencies when declaring the above?

If so, shouldn't this be covered in docs?

This behavior is not observed when using devEngines (node is not added to devDependencies when using pnpm add). Is this maybe a bug?

[zkochan]

yes, it is a bug. It shouldn't be added to the "dependencies". They are converted to dependencies internally only.

[markedwards]

yes, it is a bug. It shouldn't be added to the "dependencies". They are converted to dependencies internally only.

Thanks, I suspected something was funny here. Will look out for the fix.

[markedwards]

Another note on this subject -- I ran into problems when using engines.runtime or devEngines.runtime in the root package.json in a monorepo, without any Node installed in the system. The issue is that pnpm install fails due to post-install scripts not finding node. In that state, there was no node_modules/.bin in the root yet.

This seems to be alleviated by removing engines.runtime from the root package.json and using useNodeVersion: 24.11.1 in pnpm-workspace.yaml. So, only using engines.runtime and devEngines.runtime in individual workspace package.json.

I just wanted to mention this in case this does not align with the expected usage.

[zkochan]

I think we can make this work.

[markedwards]

Yeah, I think it would be nice to have engines.runtime and devEngines.runtime as a single consistent system for managing node without any external dependencies. This is a pretty big win for determinism across dev/CI/production, IMO.