Configuring Version Prefix for Dependency Versions

This guide explains how to configure a custom version prefix in Nx Release using the versionPrefix option. The version prefix allows you to automatically add a specific prefix format to dependencies, providing control over how dependency versions are specified in your projectโ€™s package.json files.

The versionPrefix Option

The versionPrefix option controls which prefix is applied to dependency versions during the versioning process. By default, versionPrefix is set to "auto", which selects a prefix format (either "", "~", "^", or "=") by respecting what is already in the package.json file.

For example, having the following package.json file:

1{ 2 "name": "my-package", 3 "version": "0.1.1", 4 "dependencies": { 5 "dependency-one": "~1.2.3", 6 "dependency-two": "^2.3.4", 7 "dependency-three": "3.0.0" 8 } 9} 10

Then next patch bump will be:

1{ 2 "name": "my-package", 3 "version": "0.1.2", 4 "dependencies": { 5 "dependency-one": "~1.2.4", 6 "dependency-two": "^2.3.4", 7 "dependency-three": "3.0.0" 8 } 9} 10

Preserving the prefix for dependency-one and dependency-two and continuing to use no prefix for dependency-three.

Available Prefix Options

You can set versionPrefix to one of the following values:

  • "auto": Automatically chooses a prefix based on the existing declaration in the package.json file. This is the default value.
  • "": Uses the exact version without a prefix.
  • "~": Specifies compatibility with patch-level updates.
  • "^": Specifies compatibility with minor-level updates.
  • "=": Locks the version to an exact match (the = is not commonly used in the JavaScript ecosystem, but is in others such as Cargo for Rust).

Example configuration:

1{ 2 "release": { 3 "version": { 4 "generatorOptions": { 5 "versionPrefix": "~" 6 } 7 } 8 } 9} 10

Configuring Version Prefix in nx.json or project.json

To set the versionPrefix option globally or for a specific project, add it to either your nx.json or project.json configuration files:

1{ 2 "release": { 3 "version": { 4 "generatorOptions": { 5 "versionPrefix": "^" // or "", "~", "^", "=" depending on your preference 6 } 7 } 8 } 9} 10

With the versionPrefix option set to ^, your package.json dependencies might look like this:

1{ 2 "name": "my-package", 3 "version": "0.1.1", 4 "dependencies": { 5 "dependency-one": "^1.0.0", 6 "dependency-two": "^2.3.4", 7 "dependency-three": "^3.0.0" 8 } 9} 10

This configuration helps enforce a consistent approach to dependency management, allowing flexibility in how updates to dependencies are tracked and managed across your project.