docs(release): cover version reference updates in greater detail (#29259)

docs/generated/manifests/menus.json

@@ -1268,6 +1268,14 @@
                 "children": [],
                 "disableCollapsible": false
               },
+              {
+                "name": "Updating Version References in Manifest Files (e.g. package.json)",
+                "path": "/recipes/nx-release/updating-version-references",
+                "id": "updating-version-references",
+                "isExternal": false,
+                "children": [],
+                "disableCollapsible": false
+              },
               {
                 "name": "Automatically Version with Conventional Commits",
                 "path": "/recipes/nx-release/automatically-version-with-conventional-commits",
@@ -1340,14 +1348,6 @@
                 "children": [],
                 "disableCollapsible": false
               },
-              {
-                "name": "Publish a Custom Dist Directory",
-                "path": "/recipes/nx-release/publish-custom-dist-directory",
-                "id": "publish-custom-dist-directory",
-                "isExternal": false,
-                "children": [],
-                "disableCollapsible": false
-              },
               {
                 "name": "Build Before Versioning",
                 "path": "/recipes/nx-release/build-before-versioning",
@@ -2417,6 +2417,14 @@
             "children": [],
             "disableCollapsible": false
           },
+          {
+            "name": "Updating Version References in Manifest Files (e.g. package.json)",
+            "path": "/recipes/nx-release/updating-version-references",
+            "id": "updating-version-references",
+            "isExternal": false,
+            "children": [],
+            "disableCollapsible": false
+          },
           {
             "name": "Automatically Version with Conventional Commits",
             "path": "/recipes/nx-release/automatically-version-with-conventional-commits",
@@ -2489,14 +2497,6 @@
             "children": [],
             "disableCollapsible": false
           },
-          {
-            "name": "Publish a Custom Dist Directory",
-            "path": "/recipes/nx-release/publish-custom-dist-directory",
-            "id": "publish-custom-dist-directory",
-            "isExternal": false,
-            "children": [],
-            "disableCollapsible": false
-          },
           {
             "name": "Build Before Versioning",
             "path": "/recipes/nx-release/build-before-versioning",
@@ -2532,6 +2532,14 @@
         "children": [],
         "disableCollapsible": false
       },
+      {
+        "name": "Updating Version References in Manifest Files (e.g. package.json)",
+        "path": "/recipes/nx-release/updating-version-references",
+        "id": "updating-version-references",
+        "isExternal": false,
+        "children": [],
+        "disableCollapsible": false
+      },
       {
         "name": "Automatically Version with Conventional Commits",
         "path": "/recipes/nx-release/automatically-version-with-conventional-commits",
@@ -2604,14 +2612,6 @@
         "children": [],
         "disableCollapsible": false
       },
-      {
-        "name": "Publish a Custom Dist Directory",
-        "path": "/recipes/nx-release/publish-custom-dist-directory",
-        "id": "publish-custom-dist-directory",
-        "isExternal": false,
-        "children": [],
-        "disableCollapsible": false
-      },
       {
         "name": "Build Before Versioning",
         "path": "/recipes/nx-release/build-before-versioning",

docs/generated/manifests/nx.json

@@ -1737,6 +1737,17 @@
             "path": "/recipes/nx-release/release-projects-independently",
             "tags": ["nx-release"]
           },
+          {
+            "id": "updating-version-references",
+            "name": "Updating Version References in Manifest Files (e.g. package.json)",
+            "description": "",
+            "mediaImage": "",
+            "file": "shared/recipes/nx-release/updating-version-references",
+            "itemList": [],
+            "isExternal": false,
+            "path": "/recipes/nx-release/updating-version-references",
+            "tags": ["nx-release"]
+          },
           {
             "id": "automatically-version-with-conventional-commits",
             "name": "Automatically Version with Conventional Commits",
@@ -1836,17 +1847,6 @@
             "path": "/recipes/nx-release/configure-changelog-format",
             "tags": ["nx-release"]
           },
-          {
-            "id": "publish-custom-dist-directory",
-            "name": "Publish a Custom Dist Directory",
-            "description": "",
-            "mediaImage": "",
-            "file": "shared/recipes/nx-release/publish-custom-dist-directory",
-            "itemList": [],
-            "isExternal": false,
-            "path": "/recipes/nx-release/publish-custom-dist-directory",
-            "tags": ["nx-release"]
-          },
           {
             "id": "build-before-versioning",
             "name": "Build Before Versioning",
@@ -3311,6 +3311,17 @@
         "path": "/recipes/nx-release/release-projects-independently",
         "tags": ["nx-release"]
       },
+      {
+        "id": "updating-version-references",
+        "name": "Updating Version References in Manifest Files (e.g. package.json)",
+        "description": "",
+        "mediaImage": "",
+        "file": "shared/recipes/nx-release/updating-version-references",
+        "itemList": [],
+        "isExternal": false,
+        "path": "/recipes/nx-release/updating-version-references",
+        "tags": ["nx-release"]
+      },
       {
         "id": "automatically-version-with-conventional-commits",
         "name": "Automatically Version with Conventional Commits",
@@ -3410,17 +3421,6 @@
         "path": "/recipes/nx-release/configure-changelog-format",
         "tags": ["nx-release"]
       },
-      {
-        "id": "publish-custom-dist-directory",
-        "name": "Publish a Custom Dist Directory",
-        "description": "",
-        "mediaImage": "",
-        "file": "shared/recipes/nx-release/publish-custom-dist-directory",
-        "itemList": [],
-        "isExternal": false,
-        "path": "/recipes/nx-release/publish-custom-dist-directory",
-        "tags": ["nx-release"]
-      },
       {
         "id": "build-before-versioning",
         "name": "Build Before Versioning",
@@ -3470,6 +3470,17 @@
     "path": "/recipes/nx-release/release-projects-independently",
     "tags": ["nx-release"]
   },
+  "/recipes/nx-release/updating-version-references": {
+    "id": "updating-version-references",
+    "name": "Updating Version References in Manifest Files (e.g. package.json)",
+    "description": "",
+    "mediaImage": "",
+    "file": "shared/recipes/nx-release/updating-version-references",
+    "itemList": [],
+    "isExternal": false,
+    "path": "/recipes/nx-release/updating-version-references",
+    "tags": ["nx-release"]
+  },
   "/recipes/nx-release/automatically-version-with-conventional-commits": {
     "id": "automatically-version-with-conventional-commits",
     "name": "Automatically Version with Conventional Commits",
@@ -3569,17 +3580,6 @@
     "path": "/recipes/nx-release/configure-changelog-format",
     "tags": ["nx-release"]
   },
-  "/recipes/nx-release/publish-custom-dist-directory": {
-    "id": "publish-custom-dist-directory",
-    "name": "Publish a Custom Dist Directory",
-    "description": "",
-    "mediaImage": "",
-    "file": "shared/recipes/nx-release/publish-custom-dist-directory",
-    "itemList": [],
-    "isExternal": false,
-    "path": "/recipes/nx-release/publish-custom-dist-directory",
-    "tags": ["nx-release"]
-  },
   "/recipes/nx-release/build-before-versioning": {
     "id": "build-before-versioning",
     "name": "Build Before Versioning",

docs/generated/manifests/tags.json

@@ -497,6 +497,13 @@
       "name": "Release Projects Independently",
       "path": "/recipes/nx-release/release-projects-independently"
     },
+    {
+      "description": "",
+      "file": "shared/recipes/nx-release/updating-version-references",
+      "id": "updating-version-references",
+      "name": "Updating Version References in Manifest Files (e.g. package.json)",
+      "path": "/recipes/nx-release/updating-version-references"
+    },
     {
       "description": "",
       "file": "shared/recipes/nx-release/automatically-version-with-conventional-commits",
@@ -560,13 +567,6 @@
       "name": "Configure Changelog Format",
       "path": "/recipes/nx-release/configure-changelog-format"
     },
-    {
-      "description": "",
-      "file": "shared/recipes/nx-release/publish-custom-dist-directory",
-      "id": "publish-custom-dist-directory",
-      "name": "Publish a Custom Dist Directory",
-      "path": "/recipes/nx-release/publish-custom-dist-directory"
-    },
     {
       "description": "",
       "file": "shared/recipes/nx-release/build-before-versioning",

docs/map.json

@@ -499,6 +499,12 @@
                   "tags": ["nx-release"],
                   "file": "shared/recipes/nx-release/release-projects-independently"
                 },
+                {
+                  "name": "Updating Version References in Manifest Files (e.g. package.json)",
+                  "id": "updating-version-references",
+                  "tags": ["nx-release"],
+                  "file": "shared/recipes/nx-release/updating-version-references"
+                },
                 {
                   "name": "Automatically Version with Conventional Commits",
                   "id": "automatically-version-with-conventional-commits",
@@ -553,12 +559,6 @@
                   "tags": ["nx-release"],
                   "file": "shared/recipes/nx-release/configure-changelog-format"
                 },
-                {
-                  "name": "Publish a Custom Dist Directory",
-                  "id": "publish-custom-dist-directory",
-                  "tags": ["nx-release"],
-                  "file": "shared/recipes/nx-release/publish-custom-dist-directory"
-                },
                 {
                   "name": "Build Before Versioning",
                   "id": "build-before-versioning",

docs/shared/features/manage-releases.md

@@ -20,7 +20,7 @@ nx release --dry-run
 A release can be thought about in three main phases:
 
 1. **Versioning** - The process of determining the next version of your projects, and updating any projects that depend on them to use the new version.
-2. **Changelog** - The process of deriving a changelog from your commit messages, which can be used to communicate the changes to your users.
+2. **Changelog** - The process of deriving a changelog from your commit messages or [version plan](/recipes/nx-release/file-based-versioning-version-plans) files, which can be used to communicate the changes to your users.
 3. **Publishing** - The process of publishing your projects to a registry, such as npm for TypeScript/JavaScript libraries.
 
 ## Running releases

docs/shared/recipes/nx-release/build-before-versioning.md

@@ -12,7 +12,7 @@ In order to ensure that projects are built before the new version is applied to
 }
 ```
 
-This command will run the `build` target for all projects before the version step of Nx Release. Any command can be specified, including non-nx commands. This step is often required when [publishing from a custom dist directory](/recipes/nx-release/publish-custom-dist-directory), as the dist directory must be built before the version is applied to the dist directory's package manifest.
+This command will run the `build` target for all projects before the version step of Nx Release. Any command can be specified, including non-nx commands. This step is often required when [publishing from a custom dist directory](/recipes/nx-release/updating-version-references#scenario-2-i-want-to-publish-from-a-custom-dist-directory-and-not-update-references-in-my-source-packagejson-files), as the dist directory must be built before the version is applied to the dist directory's package manifest.
 
 When using release groups in which the member projects are versioned together, you can use `groupPreVersionCommand` and it will be executed before the versioning step for that release group.
 

docs/shared/recipes/nx-release/publish-custom-dist-directory.md

@@ -1,79 +0,0 @@
-# Publish a Custom Dist Directory
-
-This recipe guides you through configuring Nx Release to version and publish packages that are built to a custom `dist` directory instead of their source project root. This is often the case when using Nx generators or custom builders that output to a centralized `dist` directory at the workspace root.
-
-## The Package Root
-
-Nx Release has the concept of a "package root", which is different than the project root. The package root is the directory from which the package is versioned and published. By default, the package root is the project root detected by Nx. Due to the modular nature of Nx Release, the package root can be configured independently for the version and publish steps.
-
-## Strategies for Tracking Dependencies
-
-Nx Release supports two out-of-the-box methods of tracking dependencies for js packages.
-
-### Use Explicit Version Numbers and Track Versions in Source Control
-
-Keep all version numbers in the source package.json file and use semantic versions when specifying dependencies. This is the default behavior. In this case, a package.json file will look like this:
-
-```json
-{
-  "name": "my-package",
-  "version": "0.1.1",
-  "dependencies": {
-    "my-other-package": "^0.1.1",
-    "my-other-package-2": "1.2.0"
-  }
-}
-```
-
-Nx Release will read the current version (0.1.1) from the source package.json file, update it to the new version, and update all dependencies in this package.json file. Changes to the package.json file will be staged and committed unless git operations are disabled. In this case, the `packageRoot` is the same as the Nx project root.
-
-### Use File or Workspace References and Do Not Track Versions in Source Control
-
-Keep all version numbers in the dist package.json file and use file or workspace references for specifying dependencies. This is done by specifying an alternate `packageRoot` for the version and publish commands. In this case, the source package.json file looks like this:
-
-```json
-{
-  "name": "my-package",
-  "dependencies": {
-    "my-other-package": "file:../my-other-package",
-    "my-other-package-2": "workspace:*"
-  }
-}
-```
-
-and the dist package.json file, which will actually be published in the publish step, looks like this:
-
-```json
-{
-  "name": "my-package",
-  "version": "0.1.1",
-  "dependencies": {
-    "my-other-package": "0.1.1",
-    "my-other-package-2": "1.2.0"
-  }
-}
-```
-
-Note that the version number is not present in the source package.json file. This is because the source package.json file is never updated in the versioning process; its data is instead written to the dist package.json file. To ensure the correct version number is used in the dist package.json file, `release.version.generatorOptions.currentVersionResolver` should be set to something other than the default value of `"disk"`. To pick the current version from git tags, set it to `"git-tag"`. To look up the current version from the remote registry, set it to `"registry"`.
-
-Configure this behavior by adding the following configuration to the `nx.json` file, or the `project.json` file of relevant projects:
-
-```jsonc {% fileName="nx.json" %}
-{
-  "release": {
-    "version": {
-      "generatorOptions": {
-        "packageRoot": "dist/packages/{projectName}", // path structure for your dist directory
-        "currentVersionResolver": "git-tag" // or "registry"
-      }
-    }
-  },
-  "targetDefaults": {
-    "nx-release-publish": {
-      "options": {
-        "packageRoot": "dist/packages/{projectName}" // path structure for your dist directory
-      }
-    }
-  }
-}
-```

docs/shared/recipes/nx-release/updating-version-references.md

@@ -0,0 +1,193 @@
+# Updating Version References in Manifest Files (e.g. package.json)
+
+The versioning stage of Nx Release is customizable and programming language agnostic, but some of its capabilities are dictated by the tooling you are using. This is particularly true when it comes to updating version references in manifest files, such as `package.json`.
+
+Nx provides the TypeScript/JavaScript (and therefore `package.json`) functionality out of the box, so that is what will be covered in more detail in this recipe. For other ecosystems, please see the documentation of the respective plugins.
+
+An important characteristic of Nx release is that it does not manipulate your packages in memory before releasing them. This maintains complete transparency between you and the tooling being leveraged to publish your packages, such as `npm publish` or `pnpm publish`, which are leveraged automatically by Nx Release during its publishing phase. The relevance of this will become clear for [Scenario 3 below](#scenario-3-i-want-to-update-package-versions-directly-in-my-source-files-but-use-local-dependency-references-via-fileworkspace).
+
+## Scenario 1: I want to update semantic version numbers directly in my source package.json files
+
+This is the simplest scenario, and default behavior of Nx Release. If you have a TypeScript/JavaScript project which lives at e.g. `packages/my-project` with its package.json at the root of the project, you can run `nx release` or use the programmatic API and it will update the version number and all relevant intra-workspace dependency references in `packages/my-project/package.json` to the new version(s).
+
+For example, with the following project structure:
+
+```
+packages/
+  my-project/
+    package.json
+  my-other-project-in-the-monorepo/
+    package.json
+```
+
+And starting point for package.json sources:
+
+```json {% fileName="packages/my-project/package.json" %}
+{
+  "name": "my-project",
+  "version": "0.1.1",
+  "dependencies": {
+    "my-other-project-in-the-monorepo": "0.1.1"
+  }
+}
+```
+
+```json {% fileName="packages/my-other-project-in-the-monorepo/package.json" %}
+{
+  "name": "my-other-project-in-the-monorepo",
+  "version": "0.1.1"
+}
+```
+
+When running `nx release` and applying a patch release, the following changes will be made to the source package.json files:
+
+```json {% fileName="packages/my-project/package.json" %}
+{
+  "name": "my-project",
+  "version": "0.1.2",
+  "dependencies": {
+    "my-other-project-in-the-monorepo": "0.1.2"
+  }
+}
+```
+
+```json {% fileName="packages/my-other-project-in-the-monorepo/package.json" %}
+{
+  "name": "my-other-project-in-the-monorepo",
+  "version": "0.1.2"
+}
+```
+
+By default, the changes will be staged and committed unless git operations are disabled.
+
+## Scenario 2: I want to publish from a custom dist directory and not update references in my source package.json files
+
+Nx Release has the concept of a "package root", which is different than the project root. The package root is the directory from which the package is versioned and published. By default, the package root is the project root detected by Nx as we have seen in Scenario 1 above, but the package root can be configured independently for the versioning and publishing steps.
+
+If we want to build our projects to a centralized `dist/` directory in the Nx workspace, we can tell Nx Release to discover it for the versioning and publishing steps by adding the following configuration to the `nx.json` file, or the `project.json` file of relevant projects:
+
+{% callout type="warning" title="The source control tracked package.json files are no longer the source of truth for the package version" %}
+Because we are no longer updating the version references in the source package.json files, the source control tracked package.json files are no longer the source of truth for the package version. We need to reference git tags or the latest value in the registry as the source of truth for the package version instead. We will also need to handle intra-workspace dependency references in the source package.json files differently using file/workspace references, which will be covered below.
+{% /callout %}
+
+```jsonc {% fileName="nx.json" %}
+{
+  "release": {
+    // Ensure that versioning works from the dist directory
+    "version": {
+      "generatorOptions": {
+        "packageRoot": "dist/packages/{projectName}", // path structure for your dist directory, where {projectRoot} and {projectName} are available placeholders that will be interpolated by Nx
+        "currentVersionResolver": "git-tag" // or "registry", because we are no longer referencing our source package.json as the source of truth for the current version
+      }
+    }
+  },
+  "targetDefaults": {
+    // Ensure that publishing works from the dist directory
+    // The nx-release-publish target is added implicitly behind the scenes by Nx Release, and we can therefore configure it in targetDefaults
+    "nx-release-publish": {
+      "options": {
+        "packageRoot": "dist/packages/{projectName}" // path structure for your dist directory, where {projectRoot} and {projectName} are available placeholders that will be interpolated by Nx
+      }
+    }
+  }
+}
+```
+
+Because our source package.json files are no longer updated during versioning, we will need to handle intra-workspace dependency references in the source package.json files differently. The way to achieve this is by using local `file:` or `workspace:` references in the source package.json files.
+
+For example, using our packages from Scenario 1 above, if we want to reference the `my-other-project-in-the-monorepo` project from `my-project`, we can update the source package.json file as follows:
+
+```jsonc {% fileName="packages/my-project/package.json" %}
+{
+  "name": "my-project", // note there is no version number in the source package.json file because it will never be updated
+  "dependencies": {
+    "my-other-project-in-the-monorepo": "workspace:*" // or "file:../my-other-project-in-the-monorepo", depending on your preference and which package manager you are using
+  }
+}
+```
+
+This reference will never need to change when versioning is carried out and the package manager will reliably link the two packages together (and tools like TypeScript can follow these references for import resolution etc).
+
+Our dist package.json will therefore ultimately look like this:
+
+```jsonc {% fileName="dist/packages/my-project/package.json" %}
+{
+  "name": "my-project",
+  "version": "0.1.2", // the version number is applied
+  "dependencies": {
+    "my-other-project-in-the-monorepo": "0.1.2" // the dependency reference is updated from the workspace reference to the actual version number
+  }
+}
+```
+
+This package.json is now valid and ready to be published to the registry.
+
+## Scenario 3: I want to update package versions directly in my source files, but use local dependency references via file/workspace
+
+{% callout type="caution" title="This scenario is only supported when your package manager is pnpm" %}
+pnpm is the only package manager that provides a publish command that supports dynamically swapping the `file:` and `workspace:*` references with the actual version number at publish time.
+{% /callout %}
+
+This is a more advanced scenario because it removes the clean separation of concerns between versioning and publishing. The reason for this is that the `file:` and `workspace:` references simply have to be replaced with actual version numbers before they are written to the registry, otherwise they will break when a user tries to install the package. If versioning does not replace them, publishing needs to.
+
+As mentioned at the start of this recipe, Nx Release intentionally does not manipulate your packages in memory during publishing, so this scenario is only supported when your package manager provides publishing functionality which dynamically swaps the local references. **Currently this is only supported by pnpm.**
+
+Let's first look at the default behavior of Nx Release, which is to update the all version references in the source package.json files with the new version number.
+
+For example, using this source package.json file, when applying a patch release:
+
+```jsonc {% fileName="packages/my-project/package.json" %}
+{
+  "name": "my-project",
+  "version": "0.1.2",
+  "dependencies": {
+    "my-other-project-in-the-monorepo": "workspace:*"
+  }
+}
+```
+
+Nx release will see this and update the "version" number to `0.1.3`, and want to replace the `workspace:*` reference with the actual version number of the dependency - also `0.1.3`. This cleanly prepares the package.json ready to be published:
+
+```jsonc {% fileName="packages/my-project/package.json" %}
+{
+  "name": "my-project",
+  "version": "0.1.3",
+  "dependencies": {
+    // whilst this is now ready to publish, it is not really what we wanted to happen,
+    // because we have now hardcoded the version number in the source package.json file
+    // and we have lost the evergreen "workspace:*" reference
+    "my-other-project-in-the-monorepo": "0.1.3"
+  }
+}
+```
+
+Now Nx release can publish this and your package will work for all its consumers, but you have the side-effect of having hardcoded the version number in the source package.json file. This is exactly what we covered in [Scenario 1 above](#scenario-1-i-want-to-update-semantic-version-numbers-directly-in-my-source-packagejson-files).
+
+To instead configure Nx Release to not update the dependency references in the source package.json files, you can set the "preserveLocalDependencyProtocols" version generator option to `true`:
+
+```jsonc {% fileName="nx.json" %}
+{
+  "release": {
+    "version": {
+      "generatorOptions": {
+        "preserveLocalDependencyProtocols": true
+      }
+    }
+  }
+}
+```
+
+Now, that same patch release to the source package.json file will result in the following:
+
+```jsonc {% fileName="packages/my-project/package.json" %}
+{
+  "name": "my-project",
+  "version": "0.1.3", // our version number is updated as expected
+  "dependencies": {
+    // our workspace dependency reference is preserved
+    "my-other-project-in-the-monorepo": "workspace:*"
+  }
+}
+```
+
+Again, this is not in a valid state to be published to the registry, and so the publishing step will need to handle this. **This is only supported by pnpm**, in which case Nx Release invokes `pnpm publish` instead of `npm publish` behind the scenes during publishing, and you will receive a clear error if you attempt to use such a package.json with another package manager.

docs/shared/reference/releases.md

@@ -1,4 +1,10 @@
-# Releases
+# Releases of the nx and @nx/\* packages
+
+{% callout type="info" title="Looking for guidance on releasing your projects with Nx Release?" %}
+This page covers the releases of the Nx tooling itself. If you are looking for guidance on releasing your project with Nx Release, [see the documentation on managing releases](/features/manage-releases).
+{% /callout %}
+
+The `nx` package, and all packages under the `@nx` namespace which live alongside each other in the [https://github.com/nrwl/nx](https://github.com/nrwl/nx) repository, are released together in lockstep. You should always use matching versions of the `nx` package and the `@nx` packages, e.g. `nx@19.2.0` and `@nx/js@20.2.0` should be used together.
 
 Major Nx versions are released as the _latest_ every six months, typically around April and October.
 After each major version release, the _previous_ major version moves to long-term support (LTS) for 12 months, after

docs/shared/reference/sitemap.md

@@ -75,6 +75,7 @@
     - [Nx Release](/recipes/nx-release)
       - [Get Started with Nx Release](/recipes/nx-release/get-started-with-nx-release)
       - [Release Projects Independently](/recipes/nx-release/release-projects-independently)
+      - [Updating Version References in Manifest Files (e.g. package.json)](/recipes/nx-release/updating-version-references)
       - [Automatically Version with Conventional Commits](/recipes/nx-release/automatically-version-with-conventional-commits)
       - [Customize Conventional Commit Types](/recipes/nx-release/customize-conventional-commit-types)
       - [File Based Versioning (Version Plans)](/recipes/nx-release/file-based-versioning-version-plans)
@@ -84,7 +85,6 @@
       - [Publish Rust Crates](/recipes/nx-release/publish-rust-crates)
       - [Update Your Local Registry Setup to use Nx Release](/recipes/nx-release/update-local-registry-setup)
       - [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)
     - [Module Federation](/recipes/module-federation)

nx-dev/nx-dev/redirect-rules.js

@@ -383,6 +383,9 @@ const recipesUrls = {
   '/recipes/nx-console/console-project-pane': '/getting-started/editor-setup',
   '/recipes/nx-console/console-add-dependency-command':
     '/getting-started/editor-setup',
+  // This one was folded into a more holistic recipe around managing version reference updates
+  '/recipes/nx-release/publish-custom-dist-directory':
+    '/recipes/nx-release/updating-version-references#scenario-2-i-want-to-publish-from-a-custom-dist-directory-and-not-update-references-in-my-source-packagejson-files',
 };
 
 /**