Files

T

fargo 1a822493ba format: apply repo prettier (3.8.1) to the folded skills tree

963 markdown files reformatted with the repository's pinned prettier so
pnpm format:check covers the folded tree like every other repo file.

The formatter's embedded-language pass also normalized code fences
(TS semicolons, closed HTML tags in examples, lowercased CSS hex colors,
one renumbered list that skipped an index). Alphanumeric token deltas vs
the fold commit were audited file-by-file; all are formatter-equivalent
markup normalizations plus the four sanitized skills.

2026-08-19 14:37:17 -05:00

4.2 KiB

Raw Blame History

name, description

name	description
pnpm-peer-dependencies	Handling peer dependencies with auto-install and resolution rules

pnpm Peer Dependencies

pnpm has strict peer dependency handling by default. It provides configuration options to control how peer dependencies are resolved and reported.

Auto-Install Peer Dependencies

By default, pnpm automatically installs peer dependencies:

# .npmrc (default is true since pnpm v8)
auto-install-peers=true

When enabled, pnpm automatically adds missing peer dependencies based on the best matching version.

Strict Peer Dependencies

Control whether peer dependency issues cause errors:

# Fail on peer dependency issues (default: false)
strict-peer-dependencies=true

When strict, pnpm will fail if:

Peer dependency is missing
Installed version doesn't match required range

Peer Dependency Rules

Configure peer dependency behavior in package.json:

{
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": ["@babel/*", "eslint"],
      "allowedVersions": {
        "react": "17 || 18"
      },
      "allowAny": ["@types/*"]
    }
  }
}

ignoreMissing

Suppress warnings for missing peer dependencies:

{
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": ["@babel/*", "eslint", "webpack"]
    }
  }
}

Use patterns:

"react" - exact package name
"@babel/*" - all packages in scope
"*" - all packages (not recommended)

allowedVersions

Allow specific versions that would otherwise cause warnings:

{
  "pnpm": {
    "peerDependencyRules": {
      "allowedVersions": {
        "react": "17 || 18",
        "webpack": "4 || 5",
        "@types/react": "*"
      }
    }
  }
}

allowAny

Allow any version for specified peer dependencies:

{
  "pnpm": {
    "peerDependencyRules": {
      "allowAny": ["@types/*", "eslint"]
    }
  }
}

Adding Peer Dependencies via Hooks

Use .pnpmfile.cjs to add missing peer dependencies:

// .pnpmfile.cjs
function readPackage(pkg, context) {
  // Add missing peer dependency
  if (pkg.name === 'problematic-package') {
    pkg.peerDependencies = {
      ...pkg.peerDependencies,
      react: '*',
    };
  }
  return pkg;
}

module.exports = {
  hooks: {
    readPackage,
  },
};

Peer Dependencies in Workspaces

Workspace packages can satisfy peer dependencies:

// packages/app/package.json
{
  "dependencies": {
    "react": "^18.2.0",
    "@myorg/components": "workspace:^"
  }
}

// packages/components/package.json
{
  "peerDependencies": {
    "react": "^17.0.0 || ^18.0.0"
  }
}

The workspace app provides react which satisfies components' peer dependency.

Common Scenarios

Monorepo with Shared React

# pnpm-workspace.yaml
catalog:
  react: ^18.2.0
  react-dom: ^18.2.0

// packages/ui/package.json
{
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}

// apps/web/package.json
{
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:",
    "@myorg/ui": "workspace:^"
  }
}

Suppress ESLint Plugin Warnings

{
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": ["eslint", "@typescript-eslint/parser"]
    }
  }
}

Allow Multiple Major Versions

{
  "pnpm": {
    "peerDependencyRules": {
      "allowedVersions": {
        "webpack": "4 || 5",
        "postcss": "7 || 8"
      }
    }
  }
}

Debugging Peer Dependencies

# See why a package is installed
pnpm why <package>

# List all peer dependency warnings
pnpm install --reporter=append-only 2>&1 | grep -i peer

# Check dependency tree
pnpm list --depth=Infinity

Best Practices

Enable auto-install-peers for convenience (default in pnpm v8+)
Use peerDependencyRules instead of ignoring all warnings
Document suppressed warnings explaining why they're safe

Keep peer deps ranges wide in libraries:

{
  "peerDependencies": {
    "react": "^17.0.0 || ^18.0.0"
  }
}

Test with different peer versions if you support multiple majors

4.2 KiB Raw Blame History