docs(core): add watch recipe (#13810)

docs/generated/manifests/menus.json

@@ -2453,6 +2453,14 @@
             "children": [],
             "disableCollapsible": false
           },
+          {
+            "name": "Workspace Watching",
+            "path": "/recipes/other/workspace-watching",
+            "id": "workspace-watching",
+            "isExternal": false,
+            "children": [],
+            "disableCollapsible": false
+          },
           {
             "name": "Advanced Update Nx",
             "path": "/recipes/other/advanced-update",
@@ -2696,6 +2704,14 @@
         "children": [],
         "disableCollapsible": false
       },
+      {
+        "name": "Workspace Watching",
+        "path": "/recipes/other/workspace-watching",
+        "id": "workspace-watching",
+        "isExternal": false,
+        "children": [],
+        "disableCollapsible": false
+      },
       {
         "name": "Advanced Update Nx",
         "path": "/recipes/other/advanced-update",

docs/generated/manifests/recipes.json

@@ -995,6 +995,16 @@
         "path": "/recipes/other/analyze-source-files",
         "tags": ["explore-graph"]
       },
+      {
+        "id": "workspace-watching",
+        "name": "Workspace Watching",
+        "description": "",
+        "file": "shared/recipes/workspace-watching",
+        "itemList": [],
+        "isExternal": false,
+        "path": "/recipes/other/workspace-watching",
+        "tags": ["workspace-watching"]
+      },
       {
         "id": "advanced-update",
         "name": "Advanced Update Nx",
@@ -1300,6 +1310,16 @@
     "path": "/recipes/other/analyze-source-files",
     "tags": ["explore-graph"]
   },
+  "/recipes/other/workspace-watching": {
+    "id": "workspace-watching",
+    "name": "Workspace Watching",
+    "description": "",
+    "file": "shared/recipes/workspace-watching",
+    "itemList": [],
+    "isExternal": false,
+    "path": "/recipes/other/workspace-watching",
+    "tags": ["workspace-watching"]
+  },
   "/recipes/other/advanced-update": {
     "id": "advanced-update",
     "name": "Advanced Update Nx",

docs/generated/manifests/tags.json

@@ -794,6 +794,13 @@
     }
   ],
   "workspace-watching": [
+    {
+      "description": "",
+      "file": "shared/recipes/workspace-watching",
+      "id": "workspace-watching",
+      "name": "Workspace Watching",
+      "path": "/recipes/other/workspace-watching"
+    },
     {
       "description": "The core Nx plugin contains the core functionality of Nx like the project graph, nx commands and task orchestration.",
       "file": "generated/packages/generated/packages/nx/documents/watch",

docs/map.json

@@ -1005,6 +1005,12 @@
               "tags": ["explore-graph"],
               "file": "shared/recipes/analyze-source-files"
             },
+            {
+              "name": "Workspace Watching",
+              "id": "workspace-watching",
+              "tags": ["workspace-watching"],
+              "file": "shared/recipes/workspace-watching"
+            },
             {
               "name": "Advanced Update Nx",
               "id": "advanced-update",

docs/shared/recipes/workspace-watching.md

@@ -0,0 +1,150 @@
+# Workspace Watching
+
+Nx can watch your workspace and execute commands based on project or files changes.
+
+{% callout type="note" title="Nx Versioning" %}
+Workspace watching is available with Nx version 15.4.0 and higher.
+{% /callout %}
+
+Imagine the following project graph with these projects:
+
+{% graph height="450px" %}
+
+```json
+{
+  "projects": [
+    {
+      "type": "lib",
+      "name": "main-lib",
+      "data": {
+        "tags": []
+      }
+    },
+    {
+      "type": "lib",
+      "name": "lib",
+      "data": {
+        "tags": []
+      }
+    },
+    {
+      "type": "lib",
+      "name": "lib2",
+      "data": {
+        "tags": []
+      }
+    },
+    {
+      "type": "lib",
+      "name": "lib3",
+      "data": {
+        "tags": []
+      }
+    }
+  ],
+  "groupByFolder": false,
+  "dependencies": {
+    "main-lib": [
+      {
+        "target": "lib",
+        "source": "main-lib",
+        "type": "direct"
+      },
+      {
+        "target": "lib2",
+        "source": "main-lib",
+        "type": "direct"
+      },
+      {
+        "target": "lib3",
+        "source": "main-lib",
+        "type": "direct"
+      }
+    ],
+    "lib": [],
+    "lib2": [],
+    "lib3": []
+  },
+  "workspaceLayout": {
+    "appsDir": "apps",
+    "libsDir": "libs"
+  },
+  "affectedProjectIds": [],
+  "focus": null,
+  "groupByFolder": false,
+  "exclude": []
+}
+```
+
+{% /graph %}
+
+Traditionally, if you want to rebuild your projects whenever they change, you would have to set up an ad-hoc watching system to watch each project. Rather than setting up a watch manually, Nx can be used to watch projects and execute a command whenever they change.
+
+With the following command, Nx is told to watch all projects, and execute `nx run $NX_PROJECT_NAME:build` for each change.
+
+```shell
+nx watch --all -- nx run \$NX_PROJECT_NAME:build
+```
+
+{% callout type="note" title="Escaping" %}
+
+Note the backslash (`\`) before the `$`. This is needed so that your shell doesn't automatically interpolate the variables.
+
+There are also some quirks if this command is ran with a package manager. [Find out how to run this command with those managers here.](#running-nx-watch-with-package-managers)
+
+{% /callout %}
+
+Now every time a package changes, Nx will run the build.
+
+If multiple packages change at the same time, Nx will run the callback for each changed project. Then if additional changes happen while a command is in progress, Nx will batch those changes, and execute them once the current command completes.
+
+## Watch Environment Variables
+
+Nx will run the watch callback command with the `$NX_PROJECT_NAME` and `$NX_FILE_CHANGES` environment variables set.
+
+- `$NX_PROJECT_NAME` will be the name of the project.
+- `$NX_FILE_CHANGES` will be a list of files that changed formatted in stdin (ie, if `file1.txt`, and `file2.txt` change, `$NX_FILE_CHANGES` will be `file1.txt file2.txt`. This allows you to pass the list of files to other commands that accept this format.)
+
+### Running Nx watch with package managers
+
+In the examples above, the `nx watch` command was run directly in the terminal. Usually environments aren't set up to include node_module bins automatically in the shell path, so using the package manager's run/exec command is used. For example, `npx`, `yarn`, `pnpm run`.
+
+When running `npx nx watch --all -- echo \$NX_PROJECT_NAME`, (or equivalent), the watch command may not execute as expected. For example, the environment variables seem to be blank.
+
+Below are the ways to run the watch with each package manager.
+
+#### pnpm
+
+```shell
+pnpm nx watch --all -- echo \$NX_PROJECT_NAME
+```
+
+#### yarn
+
+```shell
+yarn nx -- watch --all -- echo \$NX_PROJECT_NAME
+```
+
+#### npx
+
+```shell
+npx -c 'nx watch --all -- echo \$NX_PROJECT_NAME'
+```
+
+## Additional Use Cases
+
+### Watching for specific projects
+
+To watch for specific projects and echo the changed files, run this command:
+
+```shell
+nx watch --projects=app1,app2 -- echo \$NX_CHANGED_FILES
+```
+
+### Watching for dependent projects
+
+To watch for a project and it's dependencies, run this command:
+
+```shell
+nx watch --projects=app1 --includeDependentProjects -- echo \$NX_PROJECT_NAME
+```