Generated banner for Pnpm
Generated logo for Pnpm

Pnpm

Anthony FuCommunityCreated by Anthony Fu

  • Skill
  • Tool integration
  • Software development
  • MIT
  • Low risk

From the author

Node.js package manager with strict dependency resolution. Use when running pnpm specific commands, configuring workspaces via pnpm-workspace.yaml, or managing dependencies with catalogs, patches, overrides, config dependencies, or the global virtual store.
— the description by Anthony Fu

From the skill’s files

Taken from the skill’s own files (its description, section headings and stated usage). Not an AutoGineer summary, and not written by the author as one.

Node.js package manager with strict dependency resolution. Use when running pnpm specific commands, configuring workspaces via pnpm-workspace.yaml, or managing dependencies with catalogs, patches, overrides, config dependencies, or the global virtual store. pnpm is a fast, disk space efficient package manager. It uses a content-addressable store to deduplicate packages across all projects on a machine, and enforces strict dependency resolution by default, preventing phantom dependencies.

What it does

  • Core
  • Features
  • Best Practices

When to use it

  • Use when running pnpm specific commands, configuring workspaces via pnpm-workspace.yaml, or managing dependencies with catalogs, patches, overrides, config dependencies, or the global virtual store.

Advantages

The skill’s files do not state this.

Usage examples

The skill’s files do not state this.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/antfu/pnpm/download
  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip pnpm.zip -d .agents/skills

Documentation by Anthony Fu

pnpm is a fast, disk space efficient package manager. It uses a content-addressable store to deduplicate packages across all projects on a machine, and enforces strict dependency resolution by default, preventing phantom dependencies.

pnpm v12 is a Rust rewrite of v11: stable, and keeps v11's commands, flags, settings, and lockfile format — so most guidance here applies to both. A handful of v12 behaviors differ (git deps resolve via HTTPS, project-aware global bins, other package managers, packageImportMethod: auto hardlinks first on Linux) — see best-practices-migration.

Configuration model (important): pnpm settings live in pnpm-workspace.yaml (and the global config.yaml) using camelCase keys. .npmrc is used only for authentication/registry credentials, and the pnpm field of package.json is no longer read. When working in a pnpm project, check pnpm-workspace.yaml for settings/workspace structure and .npmrc only for auth. Always use --frozen-lockfile (or pnpm ci) in CI.

The skill is based on pnpm 12.18, generated at 2026-11-05. It covers v11+v12 behavior (config split, config includes, isolated global packages, allowBuilds, pmOnFail, global virtual store, native release management, workspace task orchestration, and experimental Python/Cargo support) where current docs describe them.

Core

TopicDescriptionReference
CLI Commandsinstall/add/remove/update, run, dlx/pnx, workspace, runtime, publishing (version, view, sbom, stage)core-cli
Configurationpnpm-workspace.yaml settings (camelCase), global config.yaml, config includes, packageConfigs, auth (.npmrc, auth.ini)core-config
WorkspacesMonorepo support: filtering, workspace protocol, shared lockfile, packageConfigscore-workspaces
StoreContent-addressable store, virtual store, node linker modes (incl. loaded/store loader), frozen/read-only storecore-store

Features

TopicDescriptionReference
CatalogsCentralized dependency versions; catalogMode, catalog: in overridesfeatures-catalogs
OverridesForce versions (incl. transitive & peer deps); packageExtensionsfeatures-overrides
PatchesModify third-party packages; patchedDependencies in pnpm-workspace.yamlfeatures-patches
AliasesInstall under custom names (npm:) and registry aliases (namedRegistries)features-aliases
Hooks.pnpmfile.mjs hooks (readPackage, updateConfig, beforePacking), finders, resolvers/fetchersfeatures-hooks
Peer DependenciesAuto-install, strict mode, rules, dedupePeers, peers checkfeatures-peer-deps
Config DependenciesShare hooks/settings/catalogs/patches across repos via configDependenciesfeatures-config-dependencies
Global Virtual Store & ShimsShared node_modules, git-worktree multi-agent setups, isolated global packages, project-aware bins, other package managersfeatures-global-virtual-store
Supply-Chain SecurityBuild approval (allowBuilds), permissions and agent skills, minimumReleaseAge, trustPolicy, lockfile integrityfeatures-supply-chain-security
Task OrchestrationCross-project task graphs (tasks/dependsOn), concurrency groups, priority, pnpm pipelinefeatures-task-orchestration
Release ManagementNative versioning: pnpm change/version -r/lane, lanes, epics, fixed groupsfeatures-versioning
Multi-EcosystemPython (pypi:) and Cargo (crate:) dependencies alongside npm (experimental)features-multi-ecosystem

Best Practices

TopicDescriptionReference
CI/CD SetupGitHub Actions, GitLab, Docker, pnpm ci, store caching, frozen lockfilesbest-practices-ci
Migrationnpm/Yarn → pnpm, phantom deps, and pnpm v10 → v11 → v12 upgrade notesbest-practices-migration
PerformanceInstall optimizations, allowBuilds, global virtual store, workspace parallelizationbest-practices-performance

Files

references/core-workspaces.md


name: pnpm-workspaces description: Monorepo support with workspaces for managing multiple packages

pnpm Workspaces

pnpm has built-in support for monorepos (multi-package repositories) through workspaces.

Setting Up Workspaces

Create pnpm-workspace.yaml at the repository root:

packages:
  # Include all packages in packages/ directory
  - 'packages/*'
  # Include all apps
  - 'apps/*'
  # Include nested packages
  - 'tools/*/packages/*'
  # Exclude test directories
  - '!**/test/**'
Converting from workspaces

If the root package.json has a workspaces field (npm/Yarn/Bun) and there's no pnpm-workspace.yaml, pnpm install creates one with the same patterns. An existing file is never changed (pnpm warns on mismatch); --ignore-workspace skips creation.

Workspace Protocol

Use workspace: protocol to reference local packages:

{
  "dependencies": {
    "@myorg/utils": "workspace:*",
    "@myorg/core": "workspace:^",
    "@myorg/types": "workspace:~"
  }
}
Protocol Variants
ProtocolBehaviorPublished As
workspace:*Any versionActual version (e.g., 1.2.3)
workspace:^Compatible version^1.2.3
workspace:~Patch version~1.2.3
workspace:^1.0.0Semver range^1.0.0

Filtering Packages

Run commands on specific packages using --filter:

# By package name
pnpm --filter @myorg/app build
pnpm -F @myorg/app build

# By directory path
pnpm --filter "./packages/core" test

# Glob patterns
pnpm --filter "@myorg/*" lint
pnpm --filter "!@myorg/internal-*" publish

# All packages
pnpm -r build
pnpm --recursive build
Dependency-based Filtering
# Package and all its dependencies
pnpm --filter "...@myorg/app" build

# Package and all its dependents
pnpm --filter "@myorg/core..." test

# Both directions
pnpm --filter "...@myorg/shared..." build

# Changed since git ref
pnpm --filter "...[origin/main]" test
pnpm --filter "[HEAD~5]" lint

Since v12.7.0, [<since>] compares against the merge base of the current branch and <since> (uncommitted changes still count; needs Git 2.24+), and a catalog version change in pnpm-workspace.yaml marks affected projects changed. Selectors are evaluated in order, so a later inclusion can restore a project an earlier exclusion removed; if the first selector is an exclusion, filtering starts from all projects. --no-fail-if-no-match overrides failIfNoMatch: true. Defaults can be set via testPattern and changedFilesIgnorePattern (string arrays).

Workspace Commands

Install dependencies
# Install all workspace packages
pnpm install

# Add dependency to specific package
pnpm --filter @myorg/app add lodash

# Add workspace dependency
pnpm --filter @myorg/app add @myorg/utils
Run scripts
# Run in all packages with that script
pnpm -r run build

# Recursive run/exec/test are topologically ordered by default (--no-sort disables)
pnpm -r run build
pnpm -r --workspace-concurrency=1 run build   # one at a time

# Run in parallel
pnpm -r --parallel run test

# Stream output
pnpm -r --stream run dev
Execute commands
# Run command in all packages
pnpm -r exec pwd

# Run in specific packages
pnpm --filter "./packages/**" exec rm -rf dist

Workspace Settings

Configure in pnpm-workspace.yaml using camelCase keys (these settings no longer belong in .npmrc):

packages:
  - 'packages/*'

# Link workspace packages automatically
linkWorkspacePackages: true
# Prefer workspace packages over registry
preferWorkspacePackages: true
# Single lockfile for the whole workspace (recommended)
sharedWorkspaceLockfile: true
# Workspace protocol handling on publish
saveWorkspaceProtocol: rolling
# Concurrent workspace scripts (default: min(4, CPU cores), container CPU quota aware; <=0 = cores minus abs value)
workspaceConcurrency: 4
# Use root deps to resolve peers of all projects
resolvePeersFromWorkspaceRoot: true
# Scripts required in every project (else `pnpm -r run <name>` fails)
requiredScripts:
  - build
# Allow adding deps to the workspace root without -w
ignoreWorkspaceRootCheck: false
# Downgrade dependency-cycle warnings; also turns ERR_PNPM_TASK_CYCLE into a warning
ignoreWorkspaceCycles: false

linkWorkspacePackages: true links a workspace project only where a project declares it directly; a transitive plain-range dep still comes from the registry. Use deep to link workspace projects into subdependencies too.

Cross-project task graphs

pnpm -r run <script> schedules a dependency-aware task graph. Declare relationships under tasks (with dependsOn, concurrencyGroups, priority) and run cached CI-style pnpm pipeline. See features-task-orchestration.

tasks:
  build:
    dependsOn: ['^build']   # build each workspace dependency first
  test:
    dependsOn: ['build']
Per-package configuration (packageConfigs)

There are no per-subproject .npmrc files. Set package-specific settings from the root file:

packageConfigs:
  project-1:
    saveExact: true
  project-2:
    savePrefix: '~'

Versioning & releases

pnpm versions workspaces natively: pnpm change + pnpm version -r (see features-versioning).

Publishing Workspaces

When publishing, workspace: protocols are converted:

// Before publish
{
  "dependencies": {
    "@myorg/utils": "workspace:^"
  }
}

// After publish
{
  "dependencies": {
    "@myorg/utils": "^1.2.3"
  }
}

Use --no-git-checks for publishing from CI:

pnpm publish -r --no-git-checks

Best Practices

  1. Use workspace protocol for internal dependencies

  2. Enable linkWorkspacePackages for automatic linking

  3. Use shared lockfile for consistency

  4. Filter by dependencies when building to ensure correct order

  5. Use catalogs for shared external dependency versions (defined in this same file)

  6. Keep all pnpm settings in pnpm-workspace.yaml (camelCase), not .npmrc

Example Project Structure

my-monorepo/
├── pnpm-workspace.yaml
├── package.json
├── pnpm-lock.yaml
├── packages/
│   ├── core/
│   │   └── package.json
│   ├── utils/
│   │   └── package.json
│   └── types/
│       └── package.json
└── apps/
    ├── web/
    │   └── package.json
    └── api/
        └── package.json

<!-- Source references: - https://pnpm.io/workspaces - https://pnpm.io/filtering - https://pnpm.io/workspace-task-orchestration - https://pnpm.io/cli/recursive -->

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

What our scanner noticed· Low risk

  • Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Anthony Fu
Publisher
Anthony Fu (Community)
Source
antfu/skills · skills/pnpm · commit f63e9ec
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE.md)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Anthony Fu.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download pnpm.zip