A flag --filter (ou -F) é usada para selecionar pacotes por padrão em um monorepo. Padrões podem ser usados para corresponder nomes de pacotes ou caminhos de pacotes, com suporte completo à sintaxe glob.

Atualmente, --filter é suportado por bun install e bun outdated, e também pode ser usado para executar scripts em vários pacotes de uma vez.

---

Correspondência

Nome do pacote --filter <pattern>

Padrões de nome selecionam pacotes com base no nome do pacote, conforme especificado no package.json. Por exemplo, se você tiver pacotes pkg-a, pkg-b e other, você pode corresponder todos os pacotes com *, apenas pkg-a e pkg-b com pkg*, e um pacote específico fornecendo o nome completo do pacote.

Caminho do pacote --filter ./<glob>

Padrões de caminho são especificados iniciando o padrão com ./ e selecionarão todos os pacotes em diretórios que correspondem ao padrão. Por exemplo, para corresponder todos os pacotes em subdiretórios de packages, você pode usar --filter './packages/**'. Para corresponder um pacote localizado em packages/foo, use --filter ./packages/foo.

---

bun install e bun outdated

Tanto bun install quanto bun outdated suportam a flag --filter.

bun install por padrão instalará dependências para todos os pacotes no monorepo. Para instalar dependências para pacotes específicos, use --filter.

Dado um monorepo com workspaces pkg-a, pkg-b e pkg-c em ./packages:

# Instalar dependências para todos os workspaces exceto `pkg-c`
bun install --filter '!pkg-c'

# Instalar dependências para pacotes em `./packages` (`pkg-a`, `pkg-b`, `pkg-c`)
bun install --filter './packages/*'

# Igual ao acima, mas exclui o package.json raiz
bun install --filter '!./' --filter './packages/*'

Da mesma forma, bun outdated exibirá dependências desatualizadas para todos os pacotes no monorepo, e --filter pode ser usado para restringir o comando a um subconjunto dos pacotes:

# Exibir dependências desatualizadas para workspaces começando com `pkg-`
bun outdated --filter 'pkg-*'

# Exibir dependências desatualizadas apenas para o package.json raiz
bun outdated --filter './'

Para mais informações sobre ambos os comandos, veja bun install e bun outdated.

---

Executando scripts com --filter

Use a flag --filter para executar scripts em vários pacotes de uma vez:

bun --filter <pattern> <script>

Digamos que você tenha um monorepo com dois pacotes: packages/api e packages/frontend, ambos com um script dev que iniciará um servidor de desenvolvimento local. Normalmente, você teria que abrir duas abas de terminal separadas, cd em cada diretório do pacote e executar bun dev:

cd packages/api
bun dev

# em outro terminal
cd packages/frontend
bun dev

Usando --filter, você pode executar o script dev em ambos os pacotes de uma vez:

bun --filter '*' dev

Ambos os comandos serão executados em paralelo e você verá uma interface de terminal agradável mostrando suas respectivas saídas:

Executando scripts em workspaces

Filtros respeitam sua configuração de workspace: Se você tiver um arquivo package.json que especifica quais pacotes fazem parte do workspace, --filter será restrito apenas a esses pacotes. Além disso, em um workspace você pode usar --filter para executar scripts em pacotes que estão localizados em qualquer lugar no workspace:

# Pacotes
# src/foo
# src/bar

# em src/bar: executa myscript em src/foo, sem necessidade de cd!
bun run --filter foo myscript

Ordem de dependência

O Bun respeitará a ordem de dependência ao executar scripts. Digamos que você tenha um pacote foo que depende de outro pacote bar no seu workspace, e ambos os pacotes têm um script build. Quando você executar bun --filter '*' build, você notará que foo só começará a ser executado quando bar terminar.