docs(core): sync nx package versions (#18973)

docs/generated/manifests/menus.json

@@ -2282,6 +2282,14 @@
                 "children": [],
                 "disableCollapsible": false
               },
+              {
+                "name": "Keep Nx Versions in Sync",
+                "path": "/recipes/tips-n-tricks/keep-nx-versions-in-sync",
+                "id": "keep-nx-versions-in-sync",
+                "isExternal": false,
+                "children": [],
+                "disableCollapsible": false
+              },
               {
                 "name": "Define Environment Variables",
                 "path": "/recipes/tips-n-tricks/define-environment-variables",
@@ -3687,6 +3695,14 @@
             "children": [],
             "disableCollapsible": false
           },
+          {
+            "name": "Keep Nx Versions in Sync",
+            "path": "/recipes/tips-n-tricks/keep-nx-versions-in-sync",
+            "id": "keep-nx-versions-in-sync",
+            "isExternal": false,
+            "children": [],
+            "disableCollapsible": false
+          },
           {
             "name": "Define Environment Variables",
             "path": "/recipes/tips-n-tricks/define-environment-variables",
@@ -3842,6 +3858,14 @@
         "children": [],
         "disableCollapsible": false
       },
+      {
+        "name": "Keep Nx Versions in Sync",
+        "path": "/recipes/tips-n-tricks/keep-nx-versions-in-sync",
+        "id": "keep-nx-versions-in-sync",
+        "isExternal": false,
+        "children": [],
+        "disableCollapsible": false
+      },
       {
         "name": "Define Environment Variables",
         "path": "/recipes/tips-n-tricks/define-environment-variables",

docs/generated/manifests/nx.json

@@ -2844,6 +2844,16 @@
             "path": "/recipes/tips-n-tricks/enable-tsc-batch-mode",
             "tags": []
           },
+          {
+            "id": "keep-nx-versions-in-sync",
+            "name": "Keep Nx Versions in Sync",
+            "description": "",
+            "file": "shared/recipes/tips-n-tricks/keep-nx-versions-in-sync",
+            "itemList": [],
+            "isExternal": false,
+            "path": "/recipes/tips-n-tricks/keep-nx-versions-in-sync",
+            "tags": ["automate-updating-dependencies"]
+          },
           {
             "id": "define-environment-variables",
             "name": "Define Environment Variables",
@@ -4597,6 +4607,16 @@
         "path": "/recipes/tips-n-tricks/enable-tsc-batch-mode",
         "tags": []
       },
+      {
+        "id": "keep-nx-versions-in-sync",
+        "name": "Keep Nx Versions in Sync",
+        "description": "",
+        "file": "shared/recipes/tips-n-tricks/keep-nx-versions-in-sync",
+        "itemList": [],
+        "isExternal": false,
+        "path": "/recipes/tips-n-tricks/keep-nx-versions-in-sync",
+        "tags": ["automate-updating-dependencies"]
+      },
       {
         "id": "define-environment-variables",
         "name": "Define Environment Variables",
@@ -4792,6 +4812,16 @@
     "path": "/recipes/tips-n-tricks/enable-tsc-batch-mode",
     "tags": []
   },
+  "/recipes/tips-n-tricks/keep-nx-versions-in-sync": {
+    "id": "keep-nx-versions-in-sync",
+    "name": "Keep Nx Versions in Sync",
+    "description": "",
+    "file": "shared/recipes/tips-n-tricks/keep-nx-versions-in-sync",
+    "itemList": [],
+    "isExternal": false,
+    "path": "/recipes/tips-n-tricks/keep-nx-versions-in-sync",
+    "tags": ["automate-updating-dependencies"]
+  },
   "/recipes/tips-n-tricks/define-environment-variables": {
     "id": "define-environment-variables",
     "name": "Define Environment Variables",

docs/generated/manifests/tags.json

@@ -241,6 +241,13 @@
       "name": "Automate Updating Dependencies",
       "path": "/core-features/automate-updating-dependencies"
     },
+    {
+      "description": "",
+      "file": "shared/recipes/tips-n-tricks/keep-nx-versions-in-sync",
+      "id": "keep-nx-versions-in-sync",
+      "name": "Keep Nx Versions in Sync",
+      "path": "/recipes/tips-n-tricks/keep-nx-versions-in-sync"
+    },
     {
       "description": "",
       "file": "shared/recipes/advanced-update",

docs/generated/packages/angular/documents/overview.md

@@ -17,6 +17,10 @@ more [here](/recipes/angular/migration/angular).
 
 ## Setting up the Angular plugin
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/angular` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 Adding the Angular plugin to an existing Nx workspace can be done with the following:
 
 ```shell

docs/generated/packages/esbuild/documents/overview.md

@@ -11,6 +11,10 @@ Why should you use this plugin?
 
 To create a new workspace, run `npx create-nx-workspace@latest --preset=npm`.
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/esbuild` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 To add the esbuild plugin to an existing workspace, run the following:
 
 {% tabs %}

docs/generated/packages/eslint-plugin/documents/overview.md

@@ -7,6 +7,10 @@ The `@nx/eslint-plugin` package is an ESLint plugin that contains a collection o
 
 ### Installation
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/eslint-plugin` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 In any Nx workspace, you can install `@nx/eslint-plugin` by running the following commands if the package is not already installed:
 
 {% tabs %}

docs/generated/packages/expo/documents/overview.md

@@ -14,6 +14,10 @@ To create a new workspace with expo, run the following command:
 
 Install the expo plugin
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/expo` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 {% tabs %}
 {%tab label="npm"%}
 

docs/generated/packages/jest/documents/overview.md

@@ -18,6 +18,10 @@ Add Jest to a project using the `configuration` generator from `@nx/jest`.
 
 First, install `@nx/jest`, if not already installed using your preferred package manager.
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/jest` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 ```shell
 npm install --save-dev @nx/jest
 ```

docs/generated/packages/js/documents/overview.md

@@ -4,6 +4,10 @@ The JS plugin contains executors and generators that are useful for JavaScript/T
 
 ### Installation
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/js` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 In any Nx workspace, you can install `@nx/js` by running the following commands if `@nx/js` package is not installed:
 
 {% tabs %}

docs/generated/packages/linter/documents/overview.md

@@ -4,6 +4,10 @@ The Linter plugin contains executors, generator, plugin and utilities used for l
 
 ### Installation
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/linter` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 In any Nx workspace, you can install `@nx/linter` by running the following commands if `@nx/linter` package is not installed:
 
 ```shell

docs/generated/packages/nest/documents/overview.md

@@ -21,6 +21,10 @@ Yarn users can use the following command instead:
 yarn create nx-workspace my-workspace --preset=nest
 ```
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/nest` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 To add the Nest plugin to an existing workspace, run one the following commands:
 
 ```shell

docs/generated/packages/next/documents/overview.md

@@ -10,7 +10,7 @@ The Next.js plugin contains executors and generators for managing Next.js applic
 
 To create a new Nx workspace with Next.js, run `npx create-nx-workspace@latest --preset=next`.
 
-To add Next.js to an existing Nx workspace, install the `@nx/next` package. Make sure to install the version that matches your `@nx/workspace` version.
+To add Next.js to an existing Nx workspace, install the `@nx/next` package. Make sure to install the version that matches your `nx` version.
 
 {% tabs %}
 {% tab label="npm" %}

docs/generated/packages/node/documents/overview.md

@@ -2,6 +2,10 @@ The Node Plugin contains generators and executors to manage Node applications wi
 
 ## Setting Up Node
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/node` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 To add the Node plugin to an existing workspace, run one of the following:
 
 ```shell

docs/generated/packages/react-native/documents/overview.md

@@ -30,6 +30,10 @@ npx create-nx-workspace your-workspace-name
 
 For existing Nx workspaces, install the `@nx/react-native` package to add React Native capabilities to it.
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/react-native` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 {% tabs %}
 {%tab label="npm"%}
 

docs/generated/packages/react/documents/overview.md

@@ -10,6 +10,10 @@ It provides:
 
 To create a new workspace with React, run `npx create-nx-workspace@latest --preset=react-standalone`.
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/react` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 To add the React plugin to an existing workspace, run one of the following:
 
 ```shell

docs/generated/packages/storybook/documents/overview.md

@@ -15,6 +15,10 @@ Starting with Nx 16, Storybook 7 is used by default to configure your projects.
 
 ### Add the Storybook plugin
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/storybook` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 {% tabs %}
 {% tab label="yarn" %}
 

docs/generated/packages/vite/documents/overview.md

@@ -70,6 +70,10 @@ If you do not want to create any new projects or convert any existing projects y
 
 #### Install the `@nx/vite` plugin
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/vite` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 {% tabs %}
 {% tab label="npm" %}
 

docs/generated/packages/web/documents/overview.md

@@ -8,6 +8,10 @@ The Nx Plugin for Web Components contains generators for managing Web Component
 
 To create a new workspace with web, run `npx create-nx-workspace@latest --preset=web-components`.
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/web` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 To add the web plugin to an existing workspace, run one of the following:
 
 ```shell

docs/map.json

@@ -1011,6 +1011,12 @@
                   "id": "enable-tsc-batch-mode",
                   "file": "shared/recipes/enable-tsc-batch-mode"
                 },
+                {
+                  "name": "Keep Nx Versions in Sync",
+                  "id": "keep-nx-versions-in-sync",
+                  "tags": ["automate-updating-dependencies"],
+                  "file": "shared/recipes/tips-n-tricks/keep-nx-versions-in-sync"
+                },
                 {
                   "name": "Define Environment Variables",
                   "id": "define-environment-variables",

docs/shared/core-features/automate-updating-dependencies.md

@@ -66,6 +66,28 @@ After you run all the migrations, you can remove `migrations.json` and commit an
 
 Note: You may want to keep the `migrations.json` until every branch that was created before the migration has been merged. Leaving the `migrations.json` in place allows devs to run `nx migrate --run-migrations` to apply the same migration process to their newly merged code as well.
 
+## Keep Nx Packages on the Same Version
+
+When you run `nx migrate`, the `nx` package and all the `@nx/` packages get updated to the same version. It is important to [keep these versions in sync](/recipes/tips-n-tricks/keep-nx-versions-in-sync), or you can encounter some difficult to debug errors. As long as you run `nx migrate` instead of manually changing the version numbers, you shouldn't have to worry about it.
+
+{% callout type="note" title="Use the latest nx-cloud version" %}
+The `nx-cloud` package does not need to be in sync with the other Nx packages. For best results, stay on the latest version of `nx-cloud`. The latest `nx-cloud` version supports the most recent 2 major versions of `nx`, although earlier versions of `nx` may also be compatible.
+{% /callout %}
+
+## Migrate Community Plugins Individually
+
+Community plugins should be migrated individually with:
+
+```shell
+nx migrate my-plugin
+```
+
+For a list of all the plugins you currently have installed, run:
+
+```shell
+nx report
+```
+
 ## Need to opt-out of some migrations?
 
 Sometimes you need to temporarily opt-out from some migrations because your workspace is not ready yet. You can manually adjust the `migrations.json` or run the update with the `--interactive` flag to choose which migrations you accept. Find more details in our [Advanced Update Process](/recipes/tips-n-tricks/advanced-update) guide.

docs/shared/guides/remix.md

@@ -27,6 +27,10 @@ In this recipe, we'll show you how to create a [Remix](https://remix.run) applic
 
 ## Install Nx Remix Plugin
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/remix` version that is on the same minor version as the `nx` version in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync). The `@nx/remix` package is still being developed under [nx-labs](https://github.com/nrwl/nx-labs), so the publishing cadence is not perfectly coordinated with the other Nx packages.
+{% /callout %}
+
 ```shell
 npm install --save-dev @nx/remix
 ```

docs/shared/packages/angular/angular-plugin.md

@@ -17,6 +17,10 @@ more [here](/recipes/angular/migration/angular).
 
 ## Setting up the Angular plugin
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/angular` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 Adding the Angular plugin to an existing Nx workspace can be done with the following:
 
 ```shell

docs/shared/packages/esbuild/esbuild-plugin.md

@@ -11,6 +11,10 @@ Why should you use this plugin?
 
 To create a new workspace, run `npx create-nx-workspace@latest --preset=npm`.
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/esbuild` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 To add the esbuild plugin to an existing workspace, run the following:
 
 {% tabs %}

docs/shared/packages/expo/expo-plugin.md

@@ -14,6 +14,10 @@ To create a new workspace with expo, run the following command:
 
 Install the expo plugin
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/expo` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 {% tabs %}
 {%tab label="npm"%}
 

docs/shared/packages/jest/jest-plugin.md

@@ -18,6 +18,10 @@ Add Jest to a project using the `configuration` generator from `@nx/jest`.
 
 First, install `@nx/jest`, if not already installed using your preferred package manager.
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/jest` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 ```shell
 npm install --save-dev @nx/jest
 ```

docs/shared/packages/js/js-plugin.md

@@ -4,6 +4,10 @@ The JS plugin contains executors and generators that are useful for JavaScript/T
 
 ### Installation
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/js` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 In any Nx workspace, you can install `@nx/js` by running the following commands if `@nx/js` package is not installed:
 
 {% tabs %}

docs/shared/packages/linter/eslint-plugin.md

@@ -7,6 +7,10 @@ The `@nx/eslint-plugin` package is an ESLint plugin that contains a collection o
 
 ### Installation
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/eslint-plugin` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 In any Nx workspace, you can install `@nx/eslint-plugin` by running the following commands if the package is not already installed:
 
 {% tabs %}

docs/shared/packages/linter/linter-plugin.md

@@ -4,6 +4,10 @@ The Linter plugin contains executors, generator, plugin and utilities used for l
 
 ### Installation
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/linter` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 In any Nx workspace, you can install `@nx/linter` by running the following commands if `@nx/linter` package is not installed:
 
 ```shell

docs/shared/packages/nest/nest-plugin.md

@@ -21,6 +21,10 @@ Yarn users can use the following command instead:
 yarn create nx-workspace my-workspace --preset=nest
 ```
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/nest` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 To add the Nest plugin to an existing workspace, run one the following commands:
 
 ```shell

docs/shared/packages/next/plugin-overview.md

@@ -10,7 +10,7 @@ The Next.js plugin contains executors and generators for managing Next.js applic
 
 To create a new Nx workspace with Next.js, run `npx create-nx-workspace@latest --preset=next`.
 
-To add Next.js to an existing Nx workspace, install the `@nx/next` package. Make sure to install the version that matches your `@nx/workspace` version.
+To add Next.js to an existing Nx workspace, install the `@nx/next` package. Make sure to install the version that matches your `nx` version.
 
 {% tabs %}
 {% tab label="npm" %}

docs/shared/packages/node/node-plugin.md

@@ -2,6 +2,10 @@ The Node Plugin contains generators and executors to manage Node applications wi
 
 ## Setting Up Node
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/node` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 To add the Node plugin to an existing workspace, run one of the following:
 
 ```shell

docs/shared/packages/react-native/react-native-plugin.md

@@ -30,6 +30,10 @@ npx create-nx-workspace your-workspace-name
 
 For existing Nx workspaces, install the `@nx/react-native` package to add React Native capabilities to it.
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/react-native` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 {% tabs %}
 {%tab label="npm"%}
 

docs/shared/packages/react/react-plugin.md

@@ -10,6 +10,10 @@ It provides:
 
 To create a new workspace with React, run `npx create-nx-workspace@latest --preset=react-standalone`.
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/react` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 To add the React plugin to an existing workspace, run one of the following:
 
 ```shell

docs/shared/packages/storybook/plugin-overview.md

@@ -15,6 +15,10 @@ Starting with Nx 16, Storybook 7 is used by default to configure your projects.
 
 ### Add the Storybook plugin
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/storybook` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 {% tabs %}
 {% tab label="yarn" %}
 

docs/shared/packages/vite/vite-plugin.md

@@ -70,6 +70,10 @@ If you do not want to create any new projects or convert any existing projects y
 
 #### Install the `@nx/vite` plugin
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/vite` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 {% tabs %}
 {% tab label="npm" %}
 

docs/shared/packages/web/web-plugin.md

@@ -8,6 +8,10 @@ The Nx Plugin for Web Components contains generators for managing Web Component
 
 To create a new workspace with web, run `npx create-nx-workspace@latest --preset=web-components`.
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/web` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 To add the web plugin to an existing workspace, run one of the following:
 
 ```shell

docs/shared/recipes/add-stack/add-express.md

@@ -18,6 +18,10 @@ Because we are using an Nx plugin for Express, all the features of Nx are availa
 
 ## Install the Express Plugin
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/express` version that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 {% tabs %}
 {%tab label="npm"%}
 

docs/shared/recipes/add-stack/add-svelte.md

@@ -50,6 +50,10 @@ npx create-nx-workspace@latest workspace --preset=react-monorepo --style=css --b
 
 **Add @nx/vite, svelte, and other dependencies to your workspace**
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/vite` and `@nx/js` versions that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 {% tabs %}
 {%tab label="npm"%}
 

docs/shared/recipes/add-stack/add-vue.md

@@ -30,6 +30,10 @@ create-nx-workspace@latest acme --preset=ts-standalone --nx-cloud=true
 
 **Add @nx/vite, vue, and other dependencies to your workspace**
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/vite` and `@nx/js` versions that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 {% tabs %}
 {%tab label="npm"%}
 

docs/shared/recipes/module-federation-with-ssr.md

@@ -22,6 +22,10 @@ Run the following command with the options listed to create an empty workspace.
 
 ### Install your framework plugin
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the `@nx/angular` or `@nx/react` versions that matches the version of `nx` in your repository. If the version numbers get out of sync, you can encounter some difficult to debug errors. You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 {% tabs %}
 
 {% tab label="Angular" %}

docs/shared/recipes/tips-n-tricks/keep-nx-versions-in-sync.md

@@ -0,0 +1,13 @@
+# Keep Nx Versions in Sync
+
+If your Nx plugin versions do not match the version of `nx` in your repository, you can encounter some difficult to debug errors. To get your Nx plugins back in sync, follow the steps below:
+
+1. Identify all the official Nx plugins that are used in your repo. This includes `nx` and any packages in the `@nx/` or `@nrwl/` organization scope, except for plugins that are still in [nx-labs](https://github.com/nrwl/nx-labs). Also, `nx-cloud` does not need to match the other package versions.
+2. Run `nx report` and identify the minimum and maximum version numbers for all the packages that need to by in sync.
+3. Run `nx migrate --from=[minimumVersion] --to=[maximumVersion]`. Note that all the official Nx plugin migration generators are designed to be idempotent - meaning that running them multiple times is equivalent to running them once. This allows you to run the migrations for all plugins without being concerned about re-running a migration that was already run.
+
+Review the [nx migrate](/core-features/automate-updating-dependencies) documentation for more options.
+
+## Prevention
+
+To ensure that the Nx plugin versions do not get out of sync, always run `nx migrate` when updating versions instead of manually updating modifying the `package.json` file.

docs/shared/reference/sitemap.md

@@ -171,6 +171,7 @@
       - [Convert from a Standalone Repository to an Integrated Repository](/recipes/tips-n-tricks/standalone-to-integrated)
       - [Configuring ESLint with Typescript](/recipes/tips-n-tricks/eslint)
       - [Enable Typescript Batch Mode](/recipes/tips-n-tricks/enable-tsc-batch-mode)
+      - [Keep Nx Versions in Sync](/recipes/tips-n-tricks/keep-nx-versions-in-sync)
       - [Define Environment Variables](/recipes/tips-n-tricks/define-environment-variables)
       - [Configuring Browser Support](/recipes/tips-n-tricks/browser-support)
       - [Include Assets in Build](/recipes/tips-n-tricks/include-assets-in-build)

nx-dev/nx-dev/lib/rspack/content/overview.ts

@@ -30,6 +30,10 @@ There are a number of ways to use Rspack in your existing workspace.
 
 First, make sure \`@nx/rspack\` is installed.
 
+{% callout type="note" title="Keep Nx Package Versions In Sync" %}
+Make sure to install the \`@nx/rspack\` version that matches the version of \`nx\` in your repository.  If the version numbers get out of sync, you can encounter some difficult to debug errors.  You can [fix Nx version mismatches with this recipe](/recipes/tips-n-tricks/keep-nx-versions-in-sync).
+{% /callout %}
+
 {% tabs %}
 {% tab label="npm" %}
 \`\`\`bash