Workspace Watching

Nx can watch your workspace and execute commands based on project or files changes.

Nx Versioning

Workspace watching is available with Nx version 15.4.0 and higher.

Imagine the following project graph with these projects:

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.

nx watch --all -- nx run \$NX_PROJECT_NAME:build
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.

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

pnpm nx watch --all -- echo \$NX_PROJECT_NAME

yarn

yarn nx -- watch --all -- echo \$NX_PROJECT_NAME

npx

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:

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:

nx watch --projects=app1 --includeDependentProjects -- echo \$NX_PROJECT_NAME

Reference