Catalog Protocol

The catalog: protocol lets a workspace define dependency versions once and reference them from every package.json. Updates land in one place and propagate to every consumer.

Where catalogs live

Catalogs can be declared in two files:

snpm-workspace.yaml — declare a default catalog and named catalogs inline:

packages:
  - packages/*

catalog:
  react: ^18.2.0
  typescript: ^5.4.0

catalogs:
  build:
    vite: ^5.0.0
  testing:
    vitest: ^1.0.0

snpm-catalog.yaml — standalone catalog file at the workspace root:
snpm-catalog.yaml
```
catalog:
  react: ^18.2.0

catalogs:
  build:
    vite: ^5.0.0
```

If both files define a key, snpm-workspace.yaml wins.

pnpm-workspace.yaml is also recognized and its catalog / catalogs blocks are merged in for compatibility.

Using catalog versions

Reference catalog entries from any package.json in the workspace:

apps/web/package.json

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

Syntax	Meaning
`catalog:`	Resolve from the default catalog (`catalog:` block)
`catalog:<name>`	Resolve from the named catalog (`catalogs.<name>` block)

Range syntax

Catalog values are normal npm semver ranges:

catalog:
  # caret
  react: ^18.2.0

  # exact
  lodash: 4.17.21

  # explicit range
  typescript: ">=5.0.0 <6.0.0"

  # pre-release tag
  next: "latest"

Updating a version

Edit snpm-workspace.yaml (or snpm-catalog.yaml).
Run snpm install from the workspace root.

Every package that references the catalog entry picks up the new version on the next install.

Mixing with overrides

Catalogs control direct dependency versions. To force versions on transitive dependencies, use snpm-overrides.yaml or package.json snpm.overrides / pnpm.overrides — see Configuration.

Best practices

Group catalogs by purpose — build, testing, linting. Default catalog for framework-level deps.
Pin sharp boundaries with exact versions for tools that have known regressions, and use carets for libraries you want to track within the major.
Combine with snpm-switch by pinning the snpm version in the root package.json, so the catalog rules apply to the same snpm build everywhere.
Use comments freely — both snpm-workspace.yaml and snpm-catalog.yaml are YAML, so contributors can read why a version is pinned.