Os catálogos no Bun fornecem uma maneira simples de compartilhar versões de dependência comuns entre vários pacotes em um monorepo. Em vez de especificar repetidamente as mesmas versões em cada pacote do workspace, você as define uma vez no package.json raiz e as referencia de forma consistente em todo o seu projeto.

Visão geral

Ao contrário do gerenciamento de dependências tradicional, onde cada pacote do workspace precisa especificar versões independentemente, os catálogos permitem que você:

1. Defina catálogos de versões no package.json raiz
2. Referencie essas versões com um protocolo catalog: simples
3. Atualize todos os pacotes simultaneamente alterando a versão em apenas um lugar

Isso é especialmente útil em grandes monorepos onde dezenas de pacotes precisam usar a mesma versão de dependências principais.

Como usar catálogos

Exemplo de estrutura de diretório

Considere um monorepo com a seguinte estrutura:

my-monorepo/
├── package.json
├── bun.lock
└── packages/
    ├── app/
    │   └── package.json
    ├── ui/
    │   └── package.json
    └── utils/
        └── package.json

1. Definir catálogos no package.json raiz

No seu package.json de nível raiz, adicione um campo catalog ou catalogs dentro do objeto workspaces:

{
  "name": "my-monorepo",
  "workspaces": {
    "packages": ["packages/*"],
    "catalog": {
      "react": "^19.0.0",
      "react-dom": "^19.0.0"
    },
    "catalogs": {
      "testing": {
        "jest": "30.0.0",
        "testing-library": "14.0.0"
      }
    }
  }
}

Se você colocar catalog ou catalogs no nível superior do arquivo package.json, isso também funcionará.

2. Referenciar versões do catálogo nos pacotes do workspace

Nos seus pacotes do workspace, use o protocolo catalog: para referenciar versões:

{
  "name": "app",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:",
    "jest": "catalog:testing"
  }
}

{
  "name": "ui",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  },
  "devDependencies": {
    "jest": "catalog:testing",
    "testing-library": "catalog:testing"
  }
}

3. Executar Bun Install

Execute bun install para instalar todas as dependências de acordo com as versões do catálogo.

Catalog vs Catalogs

O Bun suporta duas maneiras de definir catálogos:

1. catalog (singular): Um catálogo padrão para dependências comumente usadas

   "catalog": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   }

   Referencie simplesmente com catalog::

   "dependencies": {
     "react": "catalog:"
   }

2. catalogs (plural): Múltiplos catálogos nomeados para agrupar dependências

   "catalogs": {
     "testing": {
       "jest": "30.0.0"
     },
     "ui": {
       "tailwind": "4.0.0"
     }
   }

   Referencie com catalog:<name>:

   "dependencies": {
     "jest": "catalog:testing",
     "tailwind": "catalog:ui"
   }

Benefícios de usar catálogos

• Consistência: Garante que todos os pacotes usem a mesma versão de dependências críticas
• Manutenção: Atualize uma versão de dependência em um lugar em vez de em vários arquivos package.json
• Clareza: Torna óbvio quais dependências são padronizadas em todo o seu monorepo
• Simplicidade: Não há necessidade de estratégias complexas de resolução de versão ou ferramentas externas

Exemplo do mundo real

Aqui está um exemplo mais abrangente para uma aplicação React:

package.json raiz

{
  "name": "react-monorepo",
  "workspaces": {
    "packages": ["packages/*"],
    "catalog": {
      "react": "^19.0.0",
      "react-dom": "^19.0.0",
      "react-router-dom": "^6.15.0"
    },
    "catalogs": {
      "build": {
        "webpack": "5.88.2",
        "babel": "7.22.10"
      },
      "testing": {
        "jest": "29.6.2",
        "react-testing-library": "14.0.0"
      }
    }
  },
  "devDependencies": {
    "typescript": "5.1.6"
  }
}

{
  "name": "app",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:",
    "react-router-dom": "catalog:",
    "@monorepo/ui": "workspace:*",
    "@monorepo/utils": "workspace:*"
  },
  "devDependencies": {
    "webpack": "catalog:build",
    "babel": "catalog:build",
    "jest": "catalog:testing",
    "react-testing-library": "catalog:testing"
  }
}

{
  "name": "@monorepo/ui",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  },
  "devDependencies": {
    "jest": "catalog:testing",
    "react-testing-library": "catalog:testing"
  }
}

{
  "name": "@monorepo/utils",
  "dependencies": {
    "react": "catalog:"
  },
  "devDependencies": {
    "jest": "catalog:testing"
  }
}

Atualizando versões

Para atualizar versões em todos os pacotes, basta alterar a versão no package.json raiz:

"catalog": {
  "react": "^19.1.0",  // Atualizado de ^19.0.0
  "react-dom": "^19.1.0"  // Atualizado de ^19.0.0
}

Em seguida, execute bun install para atualizar todos os pacotes.

Integração com lockfile

O lockfile do Bun rastreia versões do catálogo, facilitando garantir instalações consistentes em diferentes ambientes. O lockfile inclui:

• As definições de catálogo do seu package.json
• A resolução de cada dependência catalogada

{
  "lockfileVersion": 1,
  "workspaces": {
    "": {
      "name": "react-monorepo",
    },
    "packages/app": {
      "name": "app",
      "dependencies": {
        "react": "catalog:",
        "react-dom": "catalog:",
        ...
      },
    },
    ...
  },
  "catalog": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    ...
  },
  "catalogs": {
    "build": {
      "webpack": "5.88.2",
      ...
    },
    ...
  },
  "packages": {
    ...
  }
}

Limitações e casos especiais

• Referências de catálogo devem corresponder a uma dependência definida em catalog ou em um dos catalogs nomeados
• Strings vazias e espaços em branco em nomes de catálogo são ignorados (tratados como catálogo padrão)
• Versões de dependência inválidas em catálogos falharão ao resolver durante bun install
• Catálogos estão disponíveis apenas dentro de workspaces; eles não podem ser usados fora do monorepo

O sistema de catálogos do Bun fornece uma maneira poderosa, porém simples, de manter a consistência em todo o seu monorepo sem introduzir complexidade adicional ao seu fluxo de trabalho.

Publicação

Quando você executa bun publish ou bun pm pack, o Bun substitui automaticamente as referências catalog: no seu package.json pelos números de versão resolvidos. O pacote publicado inclui strings semver regulares e não depende mais das suas definições de catálogo.