@lerna/filter-options
Options for lerna sub-commands that need filtering
Install lerna for access to the lerna
CLI.
Options
--scope <glob>
Include only packages with names matching the given glob.
$ lerna exec --scope my-component -- ls -la
$ lerna run --scope toolbar-* test
$ lerna run --scope package-1 --scope *-2 lint
Note: For certain globs, it may be necessary to quote the option argument to avoid premature shell expansion.
--ignore <glob>
Exclude packages with names matching the given glob.
$ lerna exec --ignore package-{1,2,5} -- ls -la
$ lerna run --ignore package-1 test
$ lerna run --ignore package-@(1|2) --ignore package-3 lint
More examples of filtering can be found here.
--no-private
Exclude private packages. They are included by default.
--since [ref]
Only include packages that have been changed since the specified ref
. If no ref is passed, it defaults to the most-recent tag.
$ lerna exec --since -- ls -la
$ lerna run test --since main
$ lerna ls --since some-branch
This can be particularly useful when used in CI, if you can obtain the target branch a PR will be going into, because you can use that as the ref
to the --since
option. This works well for PRs going into the default branch as well as feature branches.
--exclude-dependents
Exclude all transitive dependents when running a command with --since
, overriding the default "changed" algorithm.
This flag has no effect without --since
, and will throw an error in that case.
--include-dependents
Include all transitive dependents when running a command regardless of --scope
, --ignore
, or --since
.
--include-dependencies
Include all transitive dependencies when running a command regardless of --scope
, --ignore
, or --since
.
Used in combination with any command that accepts --scope
(bootstrap
, clean
, ls
, run
, exec
).
Ensures that all dependencies (and dev dependencies) of any scoped packages (either through --scope
or --ignore
) are operated on as well.
Note: This will override the --scope
and --ignore
flags.
i.e. A package matched by the --ignore
flag will still be bootstrapped if it is depended on by another package that is being bootstrapped.
This is useful for situations where you want to "set up" a single package that relies on other packages being set up.
$ lerna bootstrap --scope my-component --include-dependencies
$ lerna bootstrap --scope "package-*" --ignore "package-util-*" --include-dependencies
--include-merged-tags
$ lerna exec --since --include-merged-tags -- ls -la
Include tags from merged branches when running a command with --since
. This is only useful if you do a lot of publishing from feature branches, which is not generally recommended.
6.0.0 (2022-10-12)
Super fast, modern task-runner implementation for lerna run
As of version 6.0.0, Lerna will now delegate the implementation details of the lerna run
command to the super fast, modern task-runner (powered by Nx) by default.
If for some reason you wish to opt in to the legacy task-runner implementation details (powered by p-map
and p-queue
), you can do so by setting "useNx": false
in your lerna.json. (Please let us know via a Github issue if you feel the need to do that, however, as in general the new task-runner should just work how you expect it to as a lerna user).
Interactive configuration for lerna run
caching and task pipelines via the new lerna add-caching
command
When using the modern task-runner implementation described above, the way to get the most out of it is to tell it about the outputs of your various scripts, and also any relationships that exist between them (such as needing to run the build
script before the test
, for example).
Simply run lerna add-caching
and follow the instructions in order to generate all the relevant configuration for your workspace.
You can learn more about the configuration it generates here: https://lerna.js.org/docs/concepts/task-pipeline-configuration
Automatic loading of .env files in lerna run
with the new task-runner implementation
By default the modern task runner powered by Nx will automatically load .env
files for you. You can set --load-env-files
to false if you want to disable this behavior for any reason.
For more details about what .env
files will be loaded by default please see: https://nx.dev/recipes/environment-variables/define-environment-variables
Obsolete options in lerna run
with the new task-runner implementation
There are certain legacy options for lerna run
which are no longer applicable to the modern task-runner. Please see full details about those flags, and the reason behind their obselence, here:
https://lerna.js.org/docs/lerna6-obsolete-options
New lerna repair
command
When configuration changes over time as new versions of a tool are published it can be tricky to keep up with the changes and sometimes it's possible to miss out on optimizations as a result.
When you run the new command lerna repair
, lerna will execute a series of code migrations/codemods which update your workspace to the latest and greatest best practices for workspace configuration.
The actual codemods which run will be added to over time, but for now one you might see run on your workspace is that it will remove any explicit "useNx": true
references from lerna.json files, because that is no longer necessary and it's cleaner not to have it.
We are really excited about this feature and how we can use it to help users keep their workspaces up to date.