- Published on
Centralized Dependency Management Made Simple
- Authors
- Name
- Darcy Clarke
- X (Formerly Twitter)@darcy
We're thrilled to announce one of the most requested features: catalog support in vlt
! This powerful addition brings centralized dependency management to your projects, making it easier than ever to maintain consistent versions across workspaces while reducing duplication and simplifying updates.
What Are Catalogs?
Catalogs are centralized repositories of dependency specifications defined in your vlt.json
file. Think of them as a single source of truth for your dependency versions that can be referenced throughout your project. This approach, heavily inspired by pnpm
's implementation, solves several common pain points in monorepo and multi-workspace development:
- Centralize version management: Define dependency versions once and reuse them across multiple workspaces
- Reduce duplication: Eliminate the need to specify the same version ranges in multiple
package.json
files - Simplify updates: Update a dependency version in one place and have it apply everywhere it's used
- Maintain consistency: Ensure all workspaces use the same versions of shared dependencies
Getting Started with Catalogs
Setting up catalogs is straightforward. You can define them in your vlt.json
file using two approaches:
Default Catalog
The simplest approach is using a default catalog:
{
"catalog": {
"typescript": "^5.0.0",
"eslint": "^8.0.0",
"prettier": "^3.0.0",
"@types/node": "^20.0.0"
}
}
Named Catalogs
For more complex projects, you can create multiple named catalogs for different purposes:
{
"catalogs": {
"build": {
"typescript": "^5.0.0",
"rollup": "^4.0.0",
"esbuild": "^0.19.0"
},
"testing": {
"vitest": "^1.0.0",
"jest": "^29.0.0",
"@testing-library/react": "^14.0.0"
},
"dev": {
"eslint": "^8.0.0",
"prettier": "^3.0.0",
"husky": "^8.0.0"
}
}
}
catalog:
Protocol
Using the Once you've defined your catalogs, referencing them is simple using the new catalog:
protocol:
Default Catalog Reference
{
"dependencies": {
"typescript": "catalog:",
"prettier": "catalog:"
}
}
Named Catalog Reference
{
"devDependencies": {
"vitest": "catalog:testing",
"jest": "catalog:testing",
"eslint": "catalog:dev"
}
}
Real-World Example
Here's how we use catalogs in the vlt project itself:
vlt.json:
{
"workspaces": ["src/*", "infra/*", "www/*"],
"catalog": {
"@eslint/js": "^9.28.0",
"@types/node": "^22.15.29",
"eslint": "^9.28.0",
"prettier": "^3.6.0",
"typescript": "5.7.3",
"tap": "^21.1.0",
"tshy": "^3.0.2"
}
}
src/spec/package.json:
{
"name": "@vltpkg/spec",
"devDependencies": {
"@eslint/js": "catalog:",
"@types/node": "catalog:",
"eslint": "catalog:",
"prettier": "catalog:",
"typescript": "catalog:",
"tap": "catalog:",
"tshy": "catalog:"
}
}
This approach has dramatically simplified our dependency management across the 50+ packages in the vlt monorepo.
Installation and Management
You can install packages directly using the catalog protocol:
vlt install typescript@catalog:
vlt install vitest@catalog:testing
Adding new dependencies to catalogs is as simple as updating your vlt.json
and then referencing them with the catalog:
protocol in your package.json
files.
Advanced Features
Catalogs work seamlessly with other vlt features. You can even combine them with named registries:
{
"registries": {
"internal": "https://npm.internal.company.com"
},
"catalogs": {
"internal": {
"my-package": "^2.1.0"
}
}
}
Then reference them:
{
"dependencies": {
"my-internal-package": "internal:my-package@catalog:internal"
}
}
Best Practices
As you start using catalogs, here are some recommendations:
- Group related dependencies: Use named catalogs to organize dependencies by purpose (build tools, testing frameworks, etc.)
- Start with common dependencies: Begin by cataloging dependencies used across multiple workspaces
- Use semantic versioning: Define version ranges using semantic versioning principles
- Keep catalogs updated: Regularly review and update catalog entries for security and compatibility
Migration from Other Package Managers
If you're coming from pnpm, you'll find the catalog syntax largely compatible. Simply move your catalog definitions from pnpm-workspace.yaml
to the catalog
and catalogs
fields in vlt.json
.
What's Next?
Catalog support is available now in the latest version of vlt
. We're excited to see how the community uses this feature to simplify their dependency management workflows.
Ready to try catalogs in your project? Check out the full documentation and let us know what you think!
Have feedback or questions about catalogs? Join the conversation on Discord or open an issue on GitHub.