Catalog Protocol

The catalog protocol lets you define dependency versions once and reference them across your entire workspace.

Setup

Create snpm-catalog.yaml in your repository root:

snpm-catalog.yaml

# Default catalog
catalog:
  react: ^18.2.0
  react-dom: ^18.2.0
  typescript: ^5.0.0

# Named catalogs
catalogs:
  build:
    vite: ^5.0.0
    esbuild: ^0.19.0
  
  testing:
    vitest: ^1.0.0
    '@testing-library/react': ^14.0.0

Using Catalog Versions

Reference catalog versions in package.json using the catalog: protocol:

packages/ui/package.json

{
  "name": "@myorg/ui",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  },
  "devDependencies": {
    "vite": "catalog:build",
    "vitest": "catalog:testing"
  }
}

Syntax

Default Catalog:

# Simple version
react: ^18.2.0

# Exact version
lodash: 4.17.21

# Version range
typescript: >=5.0.0 <6.0.0

Named Catalogs:

catalogs:
  # Group by purpose
  testing:
    vitest: ^1.0.0
    jest: ^29.0.0
  
  # Group by framework
  vue:
    vue: ^3.3.0
    '@vue/compiler-sfc': ^3.3.0

Example

snpm-catalog.yaml

# Shared dependencies
catalog:
  react: ^18.2.0
  react-dom: ^18.2.0

# Named catalogs
catalogs:
  # Build tools
  build:
    vite: ^5.0.0
    typescript: ^5.0.0
  
  # Testing
  testing:
    vitest: ^1.0.0
    '@testing-library/react': ^14.0.0

apps/web/package.json

{
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  },
  "devDependencies": {
    "vite": "catalog:build",
    "typescript": "catalog:build",
    "vitest": "catalog:testing"
  }
}

Updating Versions

To update a dependency across your entire workspace:

Update the version in snpm-catalog.yaml
Run snpm install

All packages using that catalog entry will be updated.

Benefits

Version Consistency - Ensure all packages use the same version of shared dependencies.

Easy Updates - Update a dependency version in one place.

Reduced Errors - No more accidentally using different versions across your monorepo.

Best Practices

Group Related Dependencies:

# Framework dependencies in default catalog
catalog:
  react: ^18.2.0
  vue: ^3.3.0

# Grouped by purpose in named catalogs
catalogs:
  build:
    vite: ^5.0.0
    webpack: ^5.88.0
  
  testing:
    vitest: ^1.0.0
    jest: ^29.0.0

Use Semantic Versioning:

# Flexible - allows patch and minor updates
react: ^18.2.0

# Strict - exact version
lodash: 4.17.21

Document Version Choices:

catalog:
  # Using React 18 for concurrent features
  react: ^18.2.0
  
  # Pinned to avoid breaking changes
  lodash: 4.17.21