moeka-project/.agents/skills/pnpm/references/features-overrides.md

name, description

name	description
pnpm-overrides	Force specific versions of dependencies including transitive dependencies

pnpm Overrides

Overrides let you force specific versions of packages, including transitive dependencies. Useful for fixing security vulnerabilities or compatibility issues.

Basic Syntax

Define overrides in pnpm-workspace.yaml. They can only be set at the root of the project.

The pnpm.overrides field in package.json is no longer read (pnpm no longer reads any settings from package.json#pnpm). Move overrides to pnpm-workspace.yaml.

packages:
  - 'packages/*'

overrides:
  # Override all versions of a package
  lodash: ^4.17.21

  # Override specific version range
  "foo@^1.0.0": ^1.2.3

  # Override nested dependency (only zoo inside qar@1)
  "qar@1>zoo": "2"

  # Override to different package
  "underscore": "npm:lodash@^4.17.21"

  # Reference a catalog so the version stays in sync
  "react": "catalog:"

Override Patterns

Override all instances

overrides:
  lodash: ^4.17.21

Forces all lodash installations to use ^4.17.21.

Override specific parent version

overrides:
  "foo@^1.0.0": ^1.2.3

Only override foo when the requested version matches ^1.0.0.

Override nested dependency

overrides:
  "express>cookie": ^0.6.0
  "foo@1.x>bar@^2.0.0>qux": ^1.0.0

Override cookie only when it's a dependency of express.

Replace with different package

overrides:
  # Replace underscore with lodash
  "underscore": "npm:lodash@^4.17.21"
  
  # Use local file
  "some-pkg": "file:./local-pkg"
  
  # Use git
  "some-pkg": "github:user/repo#commit"

Remove a dependency

overrides:
  "unwanted-pkg": "-"
  "foo@1.0.0>bar": "-"   # great for skipping unused optionalDependencies

The - removes the package entirely.

Override peer dependencies

Overrides also apply to peerDependencies:

overrides:
  "react-dom>react": "18.1.0"

• Semver ranges, workspace:, and catalog: keep the entry as a peer dependency.
• Non-range specifiers (link:, file:) move it into dependencies.
• - removes the peer dependency entirely.

Common Use Cases

Security Fix

Force patched version of vulnerable package:

overrides:
  # Fix CVE in transitive dependency
  "minimist": "^1.2.6"
  "json5": "^2.2.3"

Deduplicate Dependencies

Force single version when multiple are installed:

overrides:
  "react": "^18.2.0"
  "react-dom": "^18.2.0"

Fix Peer Dependency Issues

overrides:
  "@types/react": "^18.2.0"

Replace Deprecated Package

overrides:
  "request": "npm:@cypress/request@^3.0.0"

Hooks Alternative

For more complex scenarios, use .pnpmfile.mjs:

function readPackage(pkg, context) {
  // Override dependency version
  if (pkg.dependencies?.lodash) {
    pkg.dependencies.lodash = '^4.17.21'
  }

  // Add missing peer dependency
  if (pkg.name === 'some-package') {
    pkg.peerDependencies = {
      ...pkg.peerDependencies,
      react: '*'
    }
  }

  return pkg
}

export const hooks = {
  readPackage
}

Or extend a manifest declaratively with packageExtensions (no JS needed):

packageExtensions:
  react-redux:
    peerDependencies:
      react-dom: '*'

Overrides vs Catalogs

Feature	Overrides	Catalogs
Affects	All dependencies (including transitive)	Direct dependencies only
Usage	Automatic	Explicit catalog: reference
Purpose	Force versions, fix issues	Version management
Granularity	Can target specific parents	Package-wide only

Debugging

Check which version is resolved:

# See resolved versions
pnpm why lodash

# List all versions
pnpm list lodash --depth=Infinity