Centralized Dependency Management Made Simple

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"
    }
  }
}

Using the catalog: Protocol

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:

1. Group related dependencies: Use named catalogs to organize dependencies by purpose (build tools, testing frameworks, etc.)
2. Start with common dependencies: Begin by cataloging dependencies used across multiple workspaces
3. Use semantic versioning: Define version ranges using semantic versioning principles
4. 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.