Filtering Packages
Filtering packages allows you to target your tasks to only the packages you care about.
Turborepo supports a pnpm
-like --filter
flag that allows you to select the packages
that will act as "entry points" into your monorepo's package/task graph.
You can filter your project by package name, package directory, whether packages include dependents/dependencies, and by changes
in git history.
turbo
will run each task against each matched package, ensuring that any dependencies
are run first, according to the pipeline
specification in turbo.json
.
Filter Syntax
Filters specify combinations of package(s)/apps, directories, and git commits to act as entrypoints for execution.
Multiple filters can be combined to select distinct sets of targets. Additionally, filters can also exclude targets. A target that matches any filter and is not explicitly excluded will be in the final entrypoint selection.
Turborepo's filter syntax is based on pnpm's filter syntax, so it should feel familiar to pnpm users.
Filter by package
Supports exact matches (--filter=my-pkg
), and globs (--filter=*my-pkg*
) are supported.
Scoped packages (@foo/bar
) can be abbreviated to just the package name (bar
) as long as the package name
is unique within the monorepo (e.g. @foo/bar
exists, but @baz/bar
does not).
The monorepo's root package can be selected using the token //
.
# Build 'my-pkg', letting turbo infer task dependencies from the pipeline defined in turbo.json
turbo run build --filter=my-pkg
# Build '@foo/bar', letting turbo infer task dependencies from the pipeline defined in turbo.json
turbo run build --filter=@foo/bar
# Build all packages that start with 'admin-', letting turbo infer task dependencies from the pipeline defined in turbo.json
turbo run build --filter=admin-*
# Run the format script from the root "package.json" file:
turbo run format --filter=//
Include dependents of matched packages
Prepend ...
to the filter. If my-app
depends on my-lib
, ...my-lib
will select my-app
and my-lib
.
Optionally including a ^
(...^my-lib
) will select all of my-lib
's dependents, but not my-lib
itself. In this case, just my-app
will be
selected.
# Test 'my-lib' and everything that depends on 'my-lib'
turbo run test --filter=...my-lib
# Test everything that depends on 'my-lib', but not 'my-lib' itself
turbo run test --filter=...^my-lib
Include dependencies of matched packages
Append ...
to the end of the filter. If my-app
depends on my-lib
, my-app...
will select my-app
and my-lib
.
Optionally including a ^
(my-app^...
) will select all of my-app
's dependencies, but not my-app
itself. In this case, just my-lib
will be selected.
# Build 'my-app' and its dependencies
turbo run build --filter=my-app...
# Build 'my-app's dependencies, but not 'my-app' itself
turbo run build --filter=my-app^...
Filter by directory or directory tree
Supports exact matches (--filter=./apps/docs
) and globs (--filter=./apps/*
).
When combined with other components, must be enclosed in {}
(--filter=...{./libs/*}
).
# Build all of the packages in the 'apps' directory
turbo run build --filter=./apps/*
# Build all of the packages in the 'libs' directory, and all the packages that depends on them
turbo run build --filter=...{./libs/*}
Filter by changed packages
Use the set of files changed since a specified commit to calculate packages. Enclose references in
[]
. For example, --filter=[HEAD^1]
will select all packages that have changed in the most recent
commit. If you need to check a specific range of commits, rather than comparing to HEAD
, you can set
both ends of the comparison via [<from commit>...<to commit>]
.
You can use --ignore
to specify changed files to be ignored in the calculation of which packages have changed.
You can additionally prepend the commit reference with ...
to match the dependencies of other components
against the changed packages. For instance, to select foo
if any of foo
's dependencies have changed in the last commit,
you can pass --filter=foo...[HEAD^1]
. Note that this feature is different from pnpm
's syntax.
# Test everything that changed in the last commit
turbo run test --filter=[HEAD^1]
# Build everything that depends on changes in branch 'my-feature'
turbo run build --filter=...[origin/my-feature]
# Build '@foo/bar' if it or any of its dependencies changed in the last commit
turbo run build --filter=@foo/bar...[HEAD^1]
# Test each package in the '@scope' scope that is in the 'packages' directory, if it has changed in the last commit
turbo run test --filter=@scope/*{./packages/*}[HEAD^1]
# Test each package that changed between 'main' and 'my-feature'
turbo run test --filter=[main...my-feature]
Excluding packages
Prepend !
to the filter. Matched packages from the entire filter will be excluded from the set of targets.
For example, match everything except @foo/bar
: --filter=!@foo/bar
. Note that you may need to escape !
as appropriate for your shell (e.g. \!
).
# Build everything except '@foo/bar'
turbo run build --filter=!@foo/bar
# Build all of the packages in the 'apps' directory, except the 'admin' package
turbo run build --filter=./apps/* --filter=!admin
Turborepo's Filter API design and docs were/are inspired by pnpm