Node.js versioning in Nixpacks

Nixpacks supports selecting a Node.js major version. The Nix package archive used by the build determines the exact minor and patch version.

Select a major version

Use one repository source of truth:

{
  "engines": {
    "node": "22"
  }
}

Nixpacks can also read .nvmrc or .node-version.

Alternatively, add a build variable in Coolify:

NIXPACKS_NODE_VERSION=22

Keep Build Variable enabled, then redeploy and inspect the build log to confirm the resolved version.

Why a range does not pin a patch release

Values such as 22, 22.x, or >=22 select a compatible major version. They do not tell Nixpacks which nixpkgs archive to use.

The selected archive contains a particular Node.js package. A build can therefore resolve Node.js 22.13.1, 22.14.0, or another 22.x release even when the application version setting has not changed.

Pin a nixpkgs archive

When the application must stay on the package set from one nixpkgs commit, add nixpacks.toml to the application source directory:

[phases.setup]
nixpkgsArchive = '51ad838b03a05b1de6f9f2a0fffecee64a9788ee'

The value is a complete commit SHA from the NixOS/nixpkgs repository. The example commit contains Node.js 22.13.1.

Redeploy and inspect the Nixpacks build log to confirm the Node.js version selected from the pinned archive.

Use a Dockerfile with an exact base-image tag or digest when exact runtime reproducibility is a deployment requirement.

Find an archive commit

To locate a nixpkgs commit for a required Node.js release:

1. Open the NixOS/nixpkgs repository.
2. Find the Node.js version definition, such as pkgs/development/web/nodejs/v22.nix.
3. Open the file history and find the commit that introduced the required version.
4. Confirm the version and source hash in that revision.
5. Copy the complete commit SHA into nixpacks.toml.
6. Deploy in a non-production environment and verify the resolved Node.js version in the build log.

For example, commit 51ad838b03a05b1de6f9f2a0fffecee64a9788ee updates the Node.js 22 package from 22.12.0 to 22.13.1.

Read the upstream nixpkgs archive configuration for the Nixpacks setting.

Node.js source-hash reference

The following values were collected from Node.js package definitions in nixpkgs history. Use them to compare the package definition in a candidate archive commit with the Node.js release you expect.

Read the Nixpacks Node provider for upstream version-selection behavior.