diff --git a/docs/generated/manifests/menus.json b/docs/generated/manifests/menus.json index 558cdcf0ba..bdc8569999 100644 --- a/docs/generated/manifests/menus.json +++ b/docs/generated/manifests/menus.json @@ -2033,6 +2033,14 @@ "isExternal": false, "children": [], "disableCollapsible": false + }, + { + "name": "Configuring Version Prefix for Dependency Versions", + "path": "/recipes/nx-release/configuration-version-prefix", + "id": "configuration-version-prefix", + "isExternal": false, + "children": [], + "disableCollapsible": false } ], "disableCollapsible": false @@ -3751,6 +3759,14 @@ "isExternal": false, "children": [], "disableCollapsible": false + }, + { + "name": "Configuring Version Prefix for Dependency Versions", + "path": "/recipes/nx-release/configuration-version-prefix", + "id": "configuration-version-prefix", + "isExternal": false, + "children": [], + "disableCollapsible": false } ], "disableCollapsible": false @@ -3859,6 +3875,14 @@ "children": [], "disableCollapsible": false }, + { + "name": "Configuring Version Prefix for Dependency Versions", + "path": "/recipes/nx-release/configuration-version-prefix", + "id": "configuration-version-prefix", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Enterprise", "path": "/nx-enterprise", diff --git a/docs/generated/manifests/nx.json b/docs/generated/manifests/nx.json index 2343114390..b33099826d 100644 --- a/docs/generated/manifests/nx.json +++ b/docs/generated/manifests/nx.json @@ -2779,6 +2779,17 @@ "isExternal": false, "path": "/recipes/nx-release/build-before-versioning", "tags": ["nx-release"] + }, + { + "id": "configuration-version-prefix", + "name": "Configuring Version Prefix for Dependency Versions", + "description": "", + "mediaImage": "", + "file": "shared/recipes/nx-release/configuration-version-prefix", + "itemList": [], + "isExternal": false, + "path": "/recipes/nx-release/configuration-version-prefix", + "tags": ["nx-release"] } ], "isExternal": false, @@ -5135,6 +5146,17 @@ "isExternal": false, "path": "/recipes/nx-release/build-before-versioning", "tags": ["nx-release"] + }, + { + "id": "configuration-version-prefix", + "name": "Configuring Version Prefix for Dependency Versions", + "description": "", + "mediaImage": "", + "file": "shared/recipes/nx-release/configuration-version-prefix", + "itemList": [], + "isExternal": false, + "path": "/recipes/nx-release/configuration-version-prefix", + "tags": ["nx-release"] } ], "isExternal": false, @@ -5284,6 +5306,17 @@ "path": "/recipes/nx-release/build-before-versioning", "tags": ["nx-release"] }, + "/recipes/nx-release/configuration-version-prefix": { + "id": "configuration-version-prefix", + "name": "Configuring Version Prefix for Dependency Versions", + "description": "", + "mediaImage": "", + "file": "shared/recipes/nx-release/configuration-version-prefix", + "itemList": [], + "isExternal": false, + "path": "/recipes/nx-release/configuration-version-prefix", + "tags": ["nx-release"] + }, "/nx-enterprise": { "id": "nx-enterprise", "name": "Enterprise", diff --git a/docs/generated/manifests/tags.json b/docs/generated/manifests/tags.json index dca877eeeb..cc0d429303 100644 --- a/docs/generated/manifests/tags.json +++ b/docs/generated/manifests/tags.json @@ -567,6 +567,13 @@ "name": "Build Before Versioning", "path": "/recipes/nx-release/build-before-versioning" }, + { + "description": "", + "file": "shared/recipes/nx-release/configuration-version-prefix", + "id": "configuration-version-prefix", + "name": "Configuring Version Prefix for Dependency Versions", + "path": "/recipes/nx-release/configuration-version-prefix" + }, { "description": "The core Nx plugin contains the core functionality of Nx like the project graph, nx commands and task orchestration.", "file": "generated/packages/nx/documents/release", diff --git a/docs/map.json b/docs/map.json index d0cb38e5e4..3810b91b46 100644 --- a/docs/map.json +++ b/docs/map.json @@ -1065,6 +1065,12 @@ "id": "build-before-versioning", "tags": ["nx-release"], "file": "shared/recipes/nx-release/build-before-versioning" + }, + { + "name": "Configuring Version Prefix for Dependency Versions", + "id": "configuration-version-prefix", + "tags": ["nx-release"], + "file": "shared/recipes/nx-release/configuration-version-prefix" } ] } diff --git a/docs/shared/recipes/nx-release/configuration-version-prefix.md b/docs/shared/recipes/nx-release/configuration-version-prefix.md new file mode 100644 index 0000000000..f13db81bea --- /dev/null +++ b/docs/shared/recipes/nx-release/configuration-version-prefix.md @@ -0,0 +1,93 @@ +# 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: + +```json +{ + "name": "my-package", + "version": "0.1.1", + "dependencies": { + "dependency-one": "~1.2.3", + "dependency-two": "^2.3.4", + "dependency-three": "3.0.0" + } +} +``` + +Then next patch bump will be: + +```json +{ + "name": "my-package", + "version": "0.1.2", + "dependencies": { + "dependency-one": "~1.2.4", + "dependency-two": "^2.3.4", + "dependency-three": "3.0.0" + } +} +``` + +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: + +```json +{ + "release": { + "version": { + "generatorOptions": { + "versionPrefix": "~" + } + } + } +} +``` + +## 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: + +```jsonc +{ + "release": { + "version": { + "generatorOptions": { + "versionPrefix": "^" // or "", "~", "^", "=" depending on your preference + } + } + } +} +``` + +With the `versionPrefix` option set to `^`, your `package.json` dependencies might look like this: + +```json +{ + "name": "my-package", + "version": "0.1.1", + "dependencies": { + "dependency-one": "^1.0.0", + "dependency-two": "^2.3.4", + "dependency-three": "^3.0.0" + } +} +``` + +This configuration helps enforce a consistent approach to dependency management, allowing flexibility in how updates to dependencies are tracked and managed across your project. diff --git a/docs/shared/reference/sitemap.md b/docs/shared/reference/sitemap.md index 8f99f60aef..0bdc6604ba 100644 --- a/docs/shared/reference/sitemap.md +++ b/docs/shared/reference/sitemap.md @@ -169,6 +169,7 @@ - [Configure Changelog Format](/recipes/nx-release/configure-changelog-format) - [Publish a Custom Dist Directory](/recipes/nx-release/publish-custom-dist-directory) - [Build Before Versioning](/recipes/nx-release/build-before-versioning) + - [Configuring Version Prefix for Dependency Versions](/recipes/nx-release/configuration-version-prefix) - [Troubleshoot Nx Console Issues](/recipes/nx-console/console-troubleshooting) - [Enterprise](/nx-enterprise) - [Activate Powerpack](/nx-enterprise/activate-powerpack)