Runtime versions

Primcloud installs the Node.js version your app asks for, resolved from the engines.node field in package.json. If you don't ask for anything, you get the current recommended LTS.

Supported versions#

The Node.js versions you can install are part of the Primcloud Runtime and move as the Runtime is updated. The build log for each deployment, in the Deployments tab, shows the version that build installed. Today the supported majors are:

Treat the table as the state today, not a fixed contract: new patch releases land in the Primcloud Runtime as the Node.js project ships them, and the supported majors move as the Runtime is updated. Odd-numbered majors (23, 25) never ship: they don't become LTS and aren't a fit for long-running production workloads.

The Node.js release schedule is the source of truth for what's active LTS today.

Pinning a version#

Set engines.node in package.json to a semver range:

{
  "engines": {
    "node": "24.x"
  }
}

Primcloud resolves the range against the versions the Runtime ships and installs the newest matching version. Common shapes:

• "24.x": latest 24.y.z release. Recommended: you get patch updates automatically.
• "^24.5.0": 24.y.z where y.z ≥ 5.0. Latest 24.
• "~24.5.0": 24.5.z. Locks major and minor.
• "24.5.1": exact version. Locks all three.
• "22.x || 24.x": accept either major. Useful during migrations.

Ranges follow the same rules as any other npm semver dependency; see semver.npmjs.com for the interactive reference.

If engines.node is unset, Primcloud installs the recommended LTS (24.x today) and notes it in the build log: Node.js version not specified, using 24.x. That's fine for a spike but not for production. Pin a range so a rebuild can't jump you to a new major without warning.

If you set an unsupported version (21.x, 23.x, or a version outside the inventory), the build fails with an "Unknown Node.js version" error.

Upgrading#

Bump the range in package.json and redeploy:

{
  "engines": {
    "node": "24.x"
  }
}

becomes:

{
  "engines": {
    "node": "26.x"
  }
}

Commit, push, and the next build pulls the newer runtime. The first build after a major bump is a little slower because the runtime layer is cold; subsequent builds reuse the cache and are back to normal speed.

Two things to check before jumping a major:

• Native modules recompile. Any package with a native addon (node-gyp) rebuilds against the new Node.js ABI. If a dependency doesn't yet support the new major, npm ci fails at install time.
• Breaking changes. Node.js's release notes list breaking changes per major. The Node.js changelog is the authoritative list; skim the migration notes before bumping in production.

When a version drops out of support#

When a Node.js major goes end-of-life on the Node.js release schedule, the Primcloud Runtime does two things in sequence:

1. EOL warning. Builds that resolve to an EOL major continue to succeed, but the build log prints a prominent warning: Node.js <version> is now End-of-Life (EOL). Runtime keeps working.
2. Eventual removal. In a later Runtime update, the EOL version is dropped from the Runtime. Builds pinned to it via engines.node then fail with "Unknown Node.js version." Builds with an open range ("22.x || 24.x") fall through to the still-supported major automatically.

Bump to a supported major before the EOL date to avoid a forced upgrade under time pressure.