packages/watch/README.md
lerna watch) - Watch command [optional] 👓Watch for changes within packages and execute commands from the root of the repository, for example, trigger a rebuild of packages when any of its files change.
Note the
watchcommand also exists in the original Lerna, however their implementation uses Nx (no surprises) to watch for file changes. Since we want to keep Lerna-Lite well... light, we opted to useChokidar, it is used by millions of packages (even ViteJS uses it), so chances are that you already have it installed directly or indirectly. Even though Lerna and Lerna-Lite differs in their internal implementations, their usage are nearly identical (apart from the Chokidar options that we also provide).We originally used
chokidar@3but later migrated tochokidar@4in Lerna-Lite v4.0
npm install @lerna-lite/watch -D
# then use it (see usage below), sure yeah why not
lerna watch
# or via pnpm
pnpm exec lerna watch
$ lerna watch -- <command>
The values $LERNA_PACKAGE_NAME and $LERNA_FILE_CHANGES will be replaced with the package name, the file that changed respectively. If multiple file changes are detected, they will all be listed and separated by a whitespace (unless a custom file delimiter is provided).
Note When using these environment variables in the shell, you will need to escape the dollar symbol with a backslash (
\$). See the examples below.
Watch all packages and echo the package name and the file that changed:
$ lerna watch -- echo \$LERNA_PACKAGE_NAME \$LERNA_FILE_CHANGES
Watch only packages "package-1", "package-3" and their dependencies:
$ lerna watch --scope "package-{1,3}" --include-dependencies -- echo \$LERNA_PACKAGE_NAME \$LERNA_FILE_CHANGES
Watch only package "package-4" and its dependents and run the test script for the package that changed:
$ lerna watch --scope="package-4" --include-dependents -- lerna run test --scope=\$LERNA_PACKAGE_NAME
Watch the /src folder of each package using the --glob option and run the test script for the package that changed:
$ lerna watch --glob=\"src\" -- lerna run test --scope=\$LERNA_PACKAGE_NAME
Since you can execute any arbitrary commands, you could use pnpm run instead of lerna run to run the tests, the glob pattern can help to limit the watch to target only spec files
$ lerna watch --glob=\"src/**/*.spec.ts\" -- pnpm -r --filter=\$LERNA_PACKAGE_NAME test
Watch for changes on "package-1" and its dependents and run the "build" script on the scoped package and its dependents:
# with lerna run
$ lerna watch --scope=package-1 --include-dependents -- lerna run build --stream --scope=\$LERNA_PACKAGE_NAME --include-dependents
# similarly with pnpm run
$ lerna watch --scope=package-1 --include-dependents -- pnpm run --stream --filter ...\$LERNA_PACKAGE_NAME build
Watch and stream two packages and run the "build" script when any files within the targeted packages changed:
$ lerna watch --scope={my-package-1,my-package-2} -- lerna run build --stream --scope=\$LERNA_PACKAGE_NAME
When using npx, the -c option must be used if also providing variables for substitution:
$ npx -c 'lerna watch -- echo \$LERNA_PACKAGE_NAME \$LERNA_FILE_CHANGES'
Note environment variables on Windows platform need to be wrapped between two
%(e.g.%LERNA_PACKAGE_NAME%), you could also install cross-env to be cross-platform.
# On Windows
"scripts": {
"watch-files": "lerna watch -- echo \"Watch file %LERNA_FILE_CHANGES% in package %LERNA_PACKAGE_NAME%\""
}
# On Windows with cross-env (cross platform)
"scripts": {
"watch-files": "lerna watch -- cross-env-shell echo \"Watch file $LERNA_FILE_CHANGES in package $LERNA_PACKAGE_NAME\""
}
Below are basic samples added directly in Lerna-Lite which are used (manually) to test its own watch command (basically what was created/used to implement & test the watch with chokidar)
Note for Windows users: When stopping
lerna watch(or any Node.js CLI run via npm/pnpm/yarn scripts) with <kbd>Ctrl+C</kbd>, you may see theTerminate batch job (Y/N)?prompt twice. This is a limitation of the Windows shell (cmd.exe) when running batch files (.cmd).
- The prompt is not caused by Lerna Lite or Node.js, but by how Windows handles batch jobs.
- There is no way to suppress this prompt from within Node.js or your scripts.
- VS Code users: You can auto-answer the first prompt by adding this to your
.vscode/settings.json:jsonThis will auto-confirm the first prompt, but you may still see a second prompt in some cases."terminal.integrated.autoReplies": { "Terminate batch job (Y/N)": "Y\r" }- The double prompt does not occur on macOS or Linux.
For more details, see npm issue #4603 and Stack Overflow.
lerna watch accepts all filter flags. Filter flags can be used to select specific packages to watch. See the examples above.
@lerna/watch
--atomic--depth--disable-globbing--follow-symlinksignored (not supported, see watch --ignored option above instead)--ignore-initial--ignore-permission-errors--interval--use-pollingawaitWriteFinish option (these options will be prefixed with awf)
Note to limit the number of files being watched, you might want to take a look at either
--ignoredand/or--globoptions. Thelerna watchcommand skips.git/,dist/andnode_modules/directories by default.
--debounceDefaults to 200 time to wait in milliseconds before collecting all file changes before emitting them into a single watch event. Basically this option is to provide enough time for lerna watch to collect all files that changed (within that period) and avoid emitting too many watch events since Chokidar has no such debounce feature. This option becomes quite important when you do code change that affects hundred of file changes at the same time, the default is 200 but you might need to adjust the delay by increasing its value (in comparison, many libraries use 500 debounce for a watch).
$ lerna watch --debounce=500 -- <command>
--file-delimiterDefaults to a whitespace, the delimiter that will be used to separate files when mutiple file changes are emitted into a single event emitted by the watch via the $LERNA_FILE_CHANGES variable.
# use a different delimiter when multiple files are displayed
$ lerna watch --file-delimiter=\";;\" -- <command>
--globProvide a Glob pattern to target specifically which files/paths to watch, note that this will be appended to the package file path that will be provided to the watch. For example, if our package is located under /home/user/monorepo/packages/pkg-1 and we define a "glob": "/src/**/*.{ts,tsx}", it will provide the following pattern /home/user/monorepo/packages/pkg-1/src/**/*.{ts,tsx} to Chokidar watch.
# glob pattern will be appended to package path that Chokidar watches
$ lerna watch --glob=\"src\**\*.ts" -- <command>
--ignoredDefine files/paths to be ignored, it could be defined as a string, array of strings or Glob pattern (anymatch-compatible definition). Also, since this is used in a monorepo setup, we already preconfigured the watch to ignore .git/, dist/ and node_modules/ directories by default.
# ignore bin folder
$ lerna watch --ignored=\"**/bin\" -- <command>
# ignore dot file
$ lerna watch --ignored=\"/(^|[/\\])\../\" -- <command>
Note the
lerna watchcommand skips.git/,dist/andnode_modules/directories by default. If you want to watch files inside any of these directories, you can pass a negated glob pattern, that islerna watch --ignored=\"!**/node_modules/**\"
[!NOTE] The watch
ignoredoption only accept glob patterns (string or array of strings) and then internally we usetinyglobbyto find out the file list of files to watch (or ignore). Please also note that this option is no longer the same as Chokidar@4ignoredoption because their implementation no longer accept globs but Lerna-Lite watch still do.
--streamStream output from child processes immediately, prefixed with the originating package name. This allows output from different packages to be interleaved.
$ lerna watch --stream -- <command>
--no-bail# Run a command, ignoring non-zero (error) exit codes
$ lerna watch --no-bail -- <command>
By default, lerna watch will exit with an error if any execution returns a non-zero exit code.
Pass --no-bail to disable this behavior, executing in all packages regardless of exit code.
--no-prefixDisable package name prefixing when output is streaming (--stream or --parallel).
This option can be useful when piping results to other processes, such as editor plugins.
--no-shellBy default, lerna watch runs the given command within a system shell (e.g., /bin/sh on Unix or cmd.exe on Windows). Pass --no-shell to disable this behavior and spawn the process directly.
# Run a dev task on file changes without an extra shell layer to avoid Node.js warnings
$ lerna watch --no-shell --scope=pkg-1 -- cross-env-shell 'pnpm run dev --filter $LERNA_PACKAGE_NAME'
This option is particularly useful for:
DEP0190 Warnings: Modern Node.js versions (v20+) emit the DEP0190 DeprecationWarning when passing raw strings containing environment variables to a shell. This is especially relevant in watch mode, where commands are triggered frequently.cross-env-shell handle variable expansion (like $LERNA_FILE_CHANGES) consistently without interference from different system shells (e.g., Bash vs. Dash).Note: When
--no-shellis active, native shell operators such as&&,|, and>will not work, as no shell is present to interpret them.
Most Chokidar options are available and exposed (except cwd and ignored because chokidar@4 itself no longer accept globs, see --ignored option to see our own custom option that accepts globs). The option descriptions below are summarized, please visit the Chokidar options website for more detailed informations.
--atomicDefault to true, if useFsEvents and usePolling are false. Automatically filters out artifacts that occur when using editors that use "atomic writes" instead of writing directly to the source file.
$ lerna watch --atomic -- <command>
--depthDefault to undefined, if set, limits how many levels of subdirectories will be traversed.
$ lerna watch --depth=99 -- <command>
--disable-globbingDefaults to false, if set to true then the strings passed to Chokidar .watch() and .add() are treated as literal path names, even if they look like globs.
$ lerna watch --disable-globbing -- <command>
Note when this flag is enabled, it would cancel the
--globoption.
--follow-symlinksDefaults to true, when false is provided, only the symlinks themselves will be watched for changes instead of following the link references and bubbling events through the link's path.
$ lerna watch --follow-symlinks -- <command>
ignored (not supported, see --ignored instead)Chokidar ignored option is not exposed because they don't support globs anymore, however Lerna-Lite watch has its own custom --ignored option which has the same name and it does accept glob patterns, so just take a look at our watch --ignored option above.
--ignore-initialDefaults to true, if set to false then add/addDir events are also emitted for matching paths while instantiating the watching as chokidar discovers these file paths (before the ready event).
$ lerna watch --ignore-initial -- <command>
--ignore-permission-errorsDefaults to true, indicates whether to watch files that don't have read permissions if possible.
$ lerna watch --ignore-permission-errors -- <command>
--intervalDefaults to 100, interval of file system polling, in milliseconds. You may also set the CHOKIDAR_INTERVAL env variable to override this option.
$ lerna watch --interval=100 -- <command>
--use-pollingDefaults to false, whether to use fs.watchFile (backed by polling), or fs.watch. If polling leads to high CPU utilization, consider setting this to false.
$ lerna watch --use-polling -- <command>
awaitWriteFinish optionThe awaitWriteFinish option can be boolean or a complex object
Note Providing a complex object is however difficult to pass to a CLI. So in order to make them accessible to the CLI, we prefixed them with "awf", the system will internally replace the option(s) with the appropriate Chokidar complex object. For example,
awfPollInterval: 200will be transformed to{ awaitWriteFinish: { pollInterval: 200 }}
--await-write-finishDefaults to false, by default the add event will fire when a file first appears on disk, before the entire file has been written. Setting awaitWriteFinish to true (or a truthy value) will poll file size, holding its add and change events until the size does not change for a configurable amount of time.
$ lerna watch --await-write-finish -- <command>
--awf-poll-intervalDefault to 100, file size polling interval, in milliseconds.
$ lerna watch --awf-poll-interval=100 -- <command>
--awf-stability-thresholdDefault to 2000, amount of time in milliseconds for a file size to remain constant before emitting its event.
$ lerna watch --awf-stability-threshold=2000 -- <command>
Lerna-Lite will set 3 separate environment variables when running the inner command. These can be used to customize the command that will be executed.
$LERNA_PACKAGE_NAME will be replaced with the name of the package that changed.$LERNA_FILE_CHANGES will be replaced with the file(s) that changed, separated by whitespace when multiple files are changed.Note When using these variables in the shell, you will need to escape the
$with a backslash (\). See all examples above.
The examples above showcase using lerna directly in the terminal. However, you could also use lerna via a package manager without adding it to your path:
pnpm:
pnpm exec lerna watch -- lerna run build --scope=\$LERNA_PACKAGE_NAME
yarn:
yarn lerna -- watch -- lerna run build --scope=\$LERNA_PACKAGE_NAME
npx:
npx -c 'lerna watch -- lerna run build --scope=\$LERNA_PACKAGE_NAME'
Note When using
npx, you will need to use-cand surround the entirelerna watchcommand in single quotes ('). Without this,npxwill try to replace the watch environment variables before passing the command tolerna, resulting in an always empty value for$LERNA_PACKAGE_NAMEand$LERNA_FILE_CHANGES.