Include the Node.js runtime version in the cache hash (matrix builds get false cache hits)

[moltar]

Summary

The Node.js runtime version is not part of turbo's cache hash. This makes CI matrices that run the same tasks across multiple Node versions largely pointless, and can cause a race when matrix legs run in parallel.

What turbo hashes today

turbo folds only the root package.json engines field into the global hash:

• crates/turborepo-task-hash/src/global_hash.rs → engines = root_package.package_json.engines(), which is passed into GlobalHashable.
• crates/turborepo-repository/src/package_json.rs → engines() just reads the literal "engines" object (string values) from the root package.json.

The actual running node binary version (process.version, node -v, the version selected by nvm / setup-node / a Docker base image) is never read into the hash.

Why this is a problem

Consider a typical CI matrix:

strategy:
  matrix:
    node: [18, 20, 22]

With engines unchanged (or absent), all three legs compute an identical global hash. So:

1. False cache hits. The first leg to finish populates the (remote) cache; the other legs replay its artifacts and test results. The matrix appears green for Node 18/20/22 but has really only validated one runtime. Runtime-specific failures are masked.
2. Parallel race. When the legs run concurrently they race to write the same cache key. Whichever writes last wins, so the cached output for that key is nondeterministic across runs.

Expected behavior

Running the same task under a different Node.js runtime should produce a different cache key, since build output and test results can legitimately differ by runtime.

Proposal

Either:

• Include the runtime Node version (and ideally the resolved package-manager version) in the global hash by default, or
• Make it a first-class, opt-in hash input (e.g. a config flag), and/or
• Document this matrix footgun prominently in the caching docs.

Workaround, and why the obvious one does not work

The only workaround that actually distinguishes matrix legs is to feed the real runtime version into globalEnv, e.g. "globalEnv": ["NODE_VERSION"], and export the true version in each leg (e.g. echo "NODE_VERSION=$(node -v)" >> "$GITHUB_ENV").

Note that adding .nvmrc / .node-version to globalDependencies does not work for the matrix case: that file pins a single version for the repo, so its contents are identical across all matrix legs (the matrix installs a version other than the pinned one). A static file that never changes between legs cannot differentiate their cache keys.

Filing as an idea per the issue-template routing. Happy to provide a minimal reproduction if it would help move this forward.

[anthonyshew]

This is a change I will be making in Turborepo 3.0.