mirrors/bun.sh
1
0
Fork 0
mirror of https://github.com/oven-sh/bun synced 2026-02-14 12:51:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update --filter docs (#16225)

Browse Source
This commit is contained in:
Dylan Conway
2025-01-07 20:23:25 -08:00
committed by GitHub
parent 84fc9b137d
commit 7161dedd5a
4 changed files with 68 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
docs/cli/filter.md
View File

@@ -1,4 +1,51 @@
Use the `--filter` flag to execute lifecycle scripts in multiple packages at once:
The `--filter` (or `-F`) flag is used for selecting packages by pattern in a monorepo. Patterns can be used to match package names or package paths, with full glob syntax support.
Currently `--filter` is supported by `bun install` and `bun outdated`, and can also be used to run scripts for multiple packages at once.
## Matching
### Package Name `--filter <pattern>`
Name patterns select packages based on the package name, as specified in `package.json`. For example, if you have packages `pkg-a`, `pkg-b` and `other`, you can match all packages with `*`, only `pkg-a` and `pkg-b` with `pkg*`, and a specific package by providing the full name of the package.
### Package Path `--filter ./<glob>`
Path patterns are specified by starting the pattern with `./`, and will select all packages in directories that match the pattern. For example, to match all packages in subdirectories of `packages`, you can use `--filter './packages/**'`. To match a package located in `packages/foo`, use `--filter ./packages/foo`.
## `bun install` and `bun outdated`
Both `bun install` and `bun outdated` support the `--filter` flag.
`bun install` by default will install dependencies for all packages in the monorepo. To install dependencies for specific packages, use `--filter`.
Given a monorepo with workspaces `pkg-a`, `pkg-b`, and `pkg-c` under `./packages`:
```bash
# Install dependencies for all workspaces except `pkg-c`
$ bun install --filter '!pkg-c'
# Install dependencies for packages in `./packages` (`pkg-a`, `pkg-b`, `pkg-c`)
$ bun install --filter './packages/*'
# Save as above, but exclude the root package.json
$ bun install --filter --filter '!./' --filter './packages/*'
```
Similarly, `bun outdated` will display outdated dependencies for all packages in the monorepo, and `--filter` can be used to restrict the command to a subset of the packages:
```bash
# Display outdated dependencies for workspaces starting with `pkg-`
$ bun outdated --filter 'pkg-*'
# Display outdated dependencies for only the root package.json
$ bun outdated --filter './'
```
For more infomation on both these commands, see [`bun install`](https://bun.sh/docs/cli/install) and [`bun outdated`](https://bun.sh/docs/cli/outdated).
## Running scripts with `--filter`
Use the `--filter` flag to execute scripts in multiple packages at once:
```bash
bun --filter <pattern> <script>
@@ -24,19 +71,7 @@ bun --filter '*' dev
Both commands will be run in parallel, and you will see a nice terminal UI showing their respective outputs:
![Terminal Output](https://github.com/oven-sh/bun/assets/48869301/2a103e42-9921-4c33-948f-a1ad6e6bac71)
## Matching
`--filter` accepts a pattern to match specific packages, either by name or by path. Patterns have full support for glob syntax.
### Package Name `--filter <pattern>`
Name patterns select packages based on the package name, as specified in `package.json`. For example, if you have packages `pkga`, `pkgb` and `other`, you can match all packages with `*`, only `pkga` and `pkgb` with `pkg*`, and a specific package by providing the full name of the package.
### Package Path `--filter ./<glob>`
Path patterns are specified by starting the pattern with `./`, and will select all packages in directories that match the pattern. For example, to match all packages in subdirectories of `packages`, you can use `--filter './packages/**'`. To match a package located in `pkgs/foo`, use `--filter ./pkgs/foo`.
## Workspaces
### Running scripts in workspaces
Filters respect your [workspace configuration](https://bun.sh/docs/install/workspaces): If you have a `package.json` file that specifies which packages are part of the workspace,
`--filter` will be restricted to only these packages. Also, in a workspace you can use `--filter` to run scripts in packages that are located anywhere in the workspace:
@@ -50,8 +85,6 @@ Filters respect your [workspace configuration](https://bun.sh/docs/install/works
bun run --filter foo myscript
```
## Dependency Order
### Dependency Order
Bun will respect package dependency order when running scripts. Say you have a package `foo` that depends on another package `bar` in your workspace, and both packages have a `build` script. When you run `bun --filter '*' build`, you will notice that `foo` will only start running once `bar` is done.
### Cyclic Dependencies

14
docs/cli/install.md
View File

@@ -81,6 +81,20 @@ Bun supports `"workspaces"` in package.json. For complete documentation refer to
}
```
## Installing dependencies for specific packages
In a monorepo, you can install the dependencies for a subset of packages using the `--filter` flag.
```bash
# Install dependencies for all workspaces except `pkg-c`
$ bun install --filter '!pkg-c'
# Install dependencies for only `pkg-a` in `./packages/pkg-a`
$ bun install --filter './packages/pkg-a'
```
For more information on filtering with `bun install`, refer to [Package Manager > Filtering](https://bun.sh/docs/cli/install#bun-install-and-bun-outdated)
## Overrides and resolutions
Bun supports npm's `"overrides"` and Yarn's `"resolutions"` in `package.json`. These are mechanisms for specifying a version range for _metadependencies_—the dependencies of your dependencies. Refer to [Package manager > Overrides and resolutions](https://bun.sh/docs/install/overrides) for complete documentation.

2
docs/cli/outdated.md
View File

@@ -59,3 +59,5 @@ If you want to do the same, but exclude the `./apps/api` workspace:
```sh
$ bun outdated --filter './apps/*' --filter '!./apps/api'
```
Refer to [Package Manager > Filtering](https://bun.sh/docs/cli/filter#bun-install-and-bun-outdated) for more information on `--filter`.

4
docs/cli/run.md
View File

@@ -153,7 +153,7 @@ $ bun run --bun vite
### Filtering
in monorepos containing multiple packages, you can use the `--filter` argument to execute scripts in many packages at once.
In monorepos containing multiple packages, you can use the `--filter` argument to execute scripts in many packages at once.
Use `bun run --filter <name_pattern> <script>` to execute `<script>` in all packages whose name matches `<name_pattern>`.
For example, if you have subdirectories containing packages named `foo`, `bar` and `baz`, running
@@ -164,7 +164,7 @@ bun run --filter 'ba*' <script>
will execute `<script>` in both `bar` and `baz`, but not in `foo`.
Find more details in the docs page for [filter](https://bun.sh/docs/cli/filter).
Find more details in the docs page for [filter](https://bun.sh/docs/cli/filter#running-scripts-with-filter).
## `bun run -` to pipe code from stdin