O Bun suporta workspaces no package.json. Workspaces facilitam o desenvolvimento de software complexo como um monorepo consistindo de vários pacotes independentes.

É comum um monorepo ter a seguinte estrutura:

<root>
├── README.md
├── bun.lock
├── package.json
├── tsconfig.json
└── packages
    ├── pkg-a
    │   ├── index.ts
    │   ├── package.json
    │   └── tsconfig.json
    ├── pkg-b
    │   ├── index.ts
    │   ├── package.json
    │   └── tsconfig.json
    └── pkg-c
        ├── index.ts
        ├── package.json
        └── tsconfig.json

No package.json raiz, a chave "workspaces" é usada para indicar quais subdiretórios devem ser considerados pacotes/workspaces dentro do monorepo. É convencional colocar todos os workspaces em um diretório chamado packages.

{
  "name": "my-project",
  "version": "1.0.0",
  "workspaces": ["packages/*"],
  "devDependencies": {
    "example-package-in-monorepo": "workspace:*"
  }
}

NOTE

**Suporte a glob** — O Bun suporta sintaxe glob completa em `"workspaces"`, incluindo padrões negativos (por exemplo `!**/excluded/**`). Veja [aqui](/pt/runtime/glob#supported-glob-patterns) para uma lista abrangente de sintaxe suportada.

{
  "name": "my-project",
  "version": "1.0.0",
  "workspaces": ["packages/**", "!packages/**/test/**", "!packages/**/template/**"]
}

Cada workspace tem seu próprio package.json. Ao referenciar outros pacotes no monorepo, semver ou protocolos de workspace (por exemplo workspace:*) podem ser usados como o campo de versão no seu package.json.

{
  "name": "pkg-a",
  "version": "1.0.0",
  "dependencies": {
    "pkg-b": "workspace:*"
  }
}

bun install instalará dependências para todos os workspaces no monorepo, deduplicando pacotes se possível. Se você quiser instalar dependências apenas para workspaces específicos, pode usar a flag --filter.

# Instalar dependências para todos os workspaces começando com `pkg-` exceto `pkg-c`
bun install --filter "pkg-*" --filter "!pkg-c"

# Caminhos também podem ser usados. Isso é equivalente ao comando acima.
bun install --filter "./packages/pkg-*" --filter "!pkg-c" # ou --filter "!./packages/pkg-c"

Ao publicar, versões workspace: são substituídas pela versão do package.json do pacote,

"workspace:*" -> "1.0.1"
"workspace:^" -> "^1.0.1"
"workspace:~" -> "~1.0.1"

Definir uma versão específica tem precedência sobre a versão do package.json do pacote,

"workspace:1.0.2" -> "1.0.2" // Mesmo que a versão atual seja 1.0.1

Workspaces têm alguns benefícios principais.

• O código pode ser dividido em partes lógicas. Se um pacote depende de outro, você pode simplesmente adicioná-lo como uma dependência no package.json. Se o pacote b depende de a, bun install instalará seu diretório local packages/a em node_modules em vez de baixá-lo do registro npm.
• As dependências podem ser deduplicadas. Se a e b compartilham uma dependência comum, ela será hoisted para o diretório node_modules raiz. Isso reduz o uso redundante de disco e minimiza problemas de "inferno de dependências" associados a ter múltiplas versões de um pacote instaladas simultaneamente.
• Executar scripts em múltiplos pacotes. Você pode usar a flag --filter para executar facilmente scripts package.json em múltiplos pacotes no seu workspace, ou --workspaces para executar scripts em todos os workspaces.

Compartilhar versões com Catálogos

Quando muitos pacotes precisam das mesmas versões de dependência, os catálogos permitem que você defina essas versões uma vez no package.json raiz e as referencie de seus workspaces usando o protocolo catalog:. Atualizar o catálogo atualiza automaticamente cada pacote que o referencia. Veja Catálogos para detalhes.

NOTE

⚡️ **Velocidade** — Instalações são rápidas, mesmo para grandes monorepos. O Bun instala o monorepo [Remix](https://github.com/remix-run/remix) em cerca de `500ms` no Linux.

• 28x mais rápido que npm install
• 12x mais rápido que yarn install (v1)
• 8x mais rápido que pnpm install