Version Management

The Problem with Distributed Versions

In a traditional multi-project setup, each presentation manages its own dependency versions:

// presentations/quarterly-review/package.json
{
  "dependencies": {
    "@slidev/cli": "^51.2.0"
  }
}

// presentations/product-launch/package.json
{
  "dependencies": {
    "@slidev/cli": "^52.0.0"
  }
}

This leads to several issues:

• Version drift: Presentations gradually diverge, making it harder to maintain consistency
• Tedious updates: Upgrading Slidev requires editing every presentation's package.json
• Compatibility risks: Different versions may have subtle behavioral differences that cause confusion

pnpm Catalog

pnpm's catalog feature solves this by defining dependency versions in a single location: pnpm-workspace.yaml.

packages:
  - 'presentations/*'

catalog:
  '@slidev/cli': ^52.11.3
  '@slidev/theme-default': latest
  '@slidev/theme-seriph': latest
  'vue': ^3.5.26

The catalog section acts as a version registry. Instead of specifying versions directly, presentations reference the catalog using the special catalog: specifier.

Using Catalog Dependencies

When you create a presentation with pnpm new, the generated package.json uses catalog references:

{
  "name": "@supaslidev/my-talk",
  "dependencies": {
    "@slidev/cli": "catalog:",
    "@slidev/theme-default": "catalog:",
    "vue": "catalog:"
  }
}

The "catalog:" value tells pnpm to look up the actual version from pnpm-workspace.yaml. When pnpm resolves dependencies, it substitutes the catalog version:

@slidev/cli: "catalog:" → "^52.11.3"
@slidev/theme-default: "catalog:" → "latest"
vue: "catalog:" → "^3.5.26"

This substitution happens at install time. The lockfile records the resolved versions, ensuring reproducible installs.

Updating Versions

To upgrade a dependency across all presentations:

1. Edit the version in pnpm-workspace.yaml:

catalog:
  '@slidev/cli': ^53.0.0 # Updated from ^52.11.3

2. Run pnpm install:

pnpm install

Every presentation using catalog: for that dependency now resolves to the new version. The lockfile updates to reflect the change, and you can verify everything works before committing.

This single-point update eliminates the risk of forgetting to update some presentations while updating others.

Adding New Catalog Entries

When you need a new shared dependency:

1. Add the entry to the catalog:

catalog:
  '@slidev/cli': ^52.11.3
  '@slidev/theme-default': latest
  '@slidev/theme-seriph': latest
  'vue': ^3.5.26
  'mermaid': ^11.0.0 # New entry

2. Reference it in presentation package.json files:

{
  "dependencies": {
    "@slidev/cli": "catalog:",
    "mermaid": "catalog:"
  }
}

3. Run pnpm install to resolve the new dependency.

Benefits of Centralized Versions

Consistency

All presentations use the same dependency versions. When someone clones the repository and runs pnpm install, they get identical versions across all presentations.

Simplified Auditing

Security vulnerabilities are addressed in one place. Update the catalog entry, run pnpm install, and every presentation gets the patched version.

Atomic Upgrades

Major version upgrades happen atomically. You can upgrade Slidev, test all presentations together, and either commit the change or revert it. No presentation is left behind on an old version.

Cleaner Diffs

Version changes appear in one file (pnpm-workspace.yaml) rather than scattered across dozens of package.json files. Pull requests that update dependencies are easier to review.

When to Use Direct Versions

While catalog dependencies are the default, you can still use direct versions when needed:

{
  "dependencies": {
    "@slidev/cli": "catalog:",
    "some-special-package": "^1.2.3"
  }
}

Use direct versions for:

• Presentation-specific dependencies: Packages only one presentation needs
• Version pinning: When a specific presentation requires a different version than the catalog provides
• Testing: Temporarily testing a different version before updating the catalog

The migrations system helps transition presentations between direct versions and catalog references when needed.

Lockfile Behavior

pnpm maintains a single pnpm-lock.yaml at the workspace root. This lockfile:

• Records the exact resolved versions for all packages
• Ensures reproducible installs across machines and CI environments
• Updates when you run pnpm install after changing catalog versions

The lockfile is the source of truth for what versions are actually installed. The catalog defines the version ranges; the lockfile pins the exact versions.

Troubleshooting

Catalog Version Not Resolving

If a catalog: reference fails to resolve:

ERR_PNPM_CATALOG_NOT_FOUND  Catalog entry not found for "some-package"

The package is missing from the catalog. Add it to pnpm-workspace.yaml:

catalog:
  'some-package': ^1.0.0

Version Mismatch After Install

If a presentation seems to have a different version than expected, check the lockfile:

pnpm why @slidev/cli

This shows the resolved version and why it was chosen. If the lockfile is stale, delete it and reinstall:

rm pnpm-lock.yaml
pnpm install

Presentation Needs Different Version

If one presentation genuinely needs a different version, use a direct version specifier instead of catalog::

{
  "dependencies": {
    "@slidev/cli": "^51.0.0"
  }
}

Document why this presentation uses a pinned version to help future maintainers.

Next Steps

Learn how the monorepo architecture leverages catalog dependencies, or explore migrations for automating version transitions across presentations.