From 2e69313f2df42f0c4de9ea00c4a5a62f299884b7 Mon Sep 17 00:00:00 2001 From: Jonathan Cammisuli Date: Wed, 21 Dec 2022 14:02:29 -0500 Subject: [PATCH] docs(core): add watch recipe (#13810) --- docs/generated/manifests/menus.json | 16 +++ docs/generated/manifests/recipes.json | 20 +++ docs/generated/manifests/tags.json | 7 + docs/map.json | 6 + docs/shared/recipes/workspace-watching.md | 150 ++++++++++++++++++++++ 5 files changed, 199 insertions(+) create mode 100644 docs/shared/recipes/workspace-watching.md diff --git a/docs/generated/manifests/menus.json b/docs/generated/manifests/menus.json index 0a238d47d9338..e5e73fe9aa548 100644 --- a/docs/generated/manifests/menus.json +++ b/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", diff --git a/docs/generated/manifests/recipes.json b/docs/generated/manifests/recipes.json index 2df3786f13eda..d8b956740bfaa 100644 --- a/docs/generated/manifests/recipes.json +++ b/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", diff --git a/docs/generated/manifests/tags.json b/docs/generated/manifests/tags.json index f7460cb8b76fb..a639faa64bf86 100644 --- a/docs/generated/manifests/tags.json +++ b/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", diff --git a/docs/map.json b/docs/map.json index 094078e46cb50..05d014be1e973 100644 --- a/docs/map.json +++ b/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", diff --git a/docs/shared/recipes/workspace-watching.md b/docs/shared/recipes/workspace-watching.md new file mode 100644 index 0000000000000..9d3c9594fa0fb --- /dev/null +++ b/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 +```