pnpm skill

needs review

This skill helps you manage Node.js projects with pnpm, ensuring strict dependency resolution, workspace awareness, and efficient, shared storage.

npx playbooks add skill antfu/skills --skill pnpm

Review the files below or copy the command above to add this skill to your agents.

Files (15)

SKILL.md

2.9 KB

---
name: pnpm
description: Node.js package manager with strict dependency resolution. Use when running pnpm specific commands, configuring workspaces, or managing dependencies with catalogs, patches, or overrides.
metadata:
  author: Anthony Fu
  version: "2026.1.28"
  source: Generated from https://github.com/pnpm/pnpm, scripts located at https://github.com/antfu/skills
---

pnpm is a fast, disk space efficient package manager. It uses a content-addressable store to deduplicate packages across all projects on a machine, saving significant disk space. pnpm enforces strict dependency resolution by default, preventing phantom dependencies. Configuration should preferably be placed in `pnpm-workspace.yaml` for pnpm-specific settings.

**Important:** When working with pnpm projects, agents should check for `pnpm-workspace.yaml` and `.npmrc` files to understand workspace structure and configuration. Always use `--frozen-lockfile` in CI environments.

> The skill is based on pnpm 10.x, generated at 2026-01-28.

## Core

| Topic | Description | Reference |
|-------|-------------|-----------|
| CLI Commands | Install, add, remove, update, run, exec, dlx, and workspace commands | [core-cli](references/core-cli.md) |
| Configuration | pnpm-workspace.yaml, .npmrc settings, and package.json fields | [core-config](references/core-config.md) |
| Workspaces | Monorepo support with filtering, workspace protocol, and shared lockfile | [core-workspaces](references/core-workspaces.md) |
| Store | Content-addressable storage, hard links, and disk efficiency | [core-store](references/core-store.md) |

## Features

| Topic | Description | Reference |
|-------|-------------|-----------|
| Catalogs | Centralized dependency version management for workspaces | [features-catalogs](references/features-catalogs.md) |
| Overrides | Force specific versions of dependencies including transitive | [features-overrides](references/features-overrides.md) |
| Patches | Modify third-party packages with custom fixes | [features-patches](references/features-patches.md) |
| Aliases | Install packages under custom names using npm: protocol | [features-aliases](references/features-aliases.md) |
| Hooks | Customize resolution with .pnpmfile.cjs hooks | [features-hooks](references/features-hooks.md) |
| Peer Dependencies | Auto-install, strict mode, and dependency rules | [features-peer-deps](references/features-peer-deps.md) |

## Best Practices

| Topic | Description | Reference |
|-------|-------------|-----------|
| CI/CD Setup | GitHub Actions, GitLab CI, Docker, and caching strategies | [best-practices-ci](references/best-practices-ci.md) |
| Migration | Migrating from npm/Yarn, handling phantom deps, monorepo migration | [best-practices-migration](references/best-practices-migration.md) |
| Performance | Install optimizations, store caching, workspace parallelization | [best-practices-performance](references/best-practices-performance.md) |

Overview

This skill provides actionable guidance and command patterns for using pnpm, the fast and disk-efficient Node.js package manager with strict dependency resolution. It helps agents detect pnpm workspaces, apply workspace-aware commands, and follow CI best practices like using --frozen-lockfile. Use it to manage monorepos, catalogs, overrides, and patches reliably.

How this skill works

The skill inspects repository files such as pnpm-workspace.yaml and .npmrc to determine workspace boundaries and configuration. It maps common pnpm CLI commands (install, add, remove, update, run, exec, dlx, workspace) to recommended usage patterns and flags. It also covers workspace protocols, content-addressable store behavior, and features for catalogs, overrides, and patches so agents can produce correct dependency operations.

When to use it

When running pnpm-specific commands in a project or CI job
When configuring or querying workspace structure via pnpm-workspace.yaml
When adding, removing, or updating dependencies with strict resolution requirements
When applying catalogs, overrides, or patches across a monorepo
When optimizing installs with store caching or troubleshooting phantom dependencies

Best practices

Check for pnpm-workspace.yaml and .npmrc before running commands to respect project configuration
Use --frozen-lockfile in CI to ensure deterministic installs and fail fast on lockfile drift
Prefer configuration in pnpm-workspace.yaml for workspace-level settings and avoid scattering pnpm-specific options
Leverage the content-addressable store and cache in CI to speed builds and save disk space
Use overrides and patches sparingly and document reasons so transitive fixes remain maintainable

Example use cases

Install dependencies in a workspace root with workspace filtering: pnpm -w install or pnpm -w --filter "..." install
Add a dependency to a single workspace package: pnpm --filter ./packages/ui add react@^18
Apply an override to force a transitive version across the workspace via package.json overrides or pnpm config
Patch a third-party package: add a patch file and run pnpm patch <pkg>, then publish the patch and pin it in workspace config
Run a script across selected packages: pnpm -w --filter "name:^lib-" run build

FAQ

Should agents prefer pnpm-specific files over package.json for workspace info?

Yes. Check pnpm-workspace.yaml and .npmrc first for workspace layout and pnpm-specific settings; package.json is supplemental.

What flag should CI always use?

Use --frozen-lockfile in CI to prevent automatic lockfile updates and ensure reproducible installs.