Pnpm Knowledge Patch

pnpm Knowledge Patch

Use this skill for pnpm installation, workspace configuration, dependency policy, runtime management, publishing, registry authentication, release management, and migration work.

Start Here

Before changing a project:

1. Read the root manifest and identify packageManager or devEngines.packageManager.
2. Read pnpm-workspace.yaml, the lockfile, and only the registry/authentication portions of .npmrc.
3. Check whether the project is migrating between pnpm major versions.
4. Preserve the project's existing linker, store, catalog, build-permission, release-age, and trust policies unless the task explicitly changes them.
5. Use the reference index below for the exact command or setting behavior.

Treat the manifest, lockfile, repository configuration, and observed command behavior as the source of truth when they differ from generic assumptions.

Reference Index

Breaking Changes First

Migrate configuration deliberately

pnpm 11 does not read the pnpm object in package.json. Keep registry and authentication settings in .npmrc and move other settings to camelCase keys in pnpm-workspace.yaml. Use:

pnpx codemod run pnpm-v10-to-v11

Review the result manually:

• Replace the three package-manager selection settings with pmOnFail.
• Convert audit exclusions from CVEs to GHSA identifiers.
• Move per-project Node runtime declarations to devEngines.runtime.
• Rename configuration environment variables from npm_config_* to pnpm_config_* where they configure pnpm itself.
• Supply a filesystem path to pnpm link.
• Replace argument-free global install and removed server workflows.

Read Migration and dependency-build security before committing a migration.

Account for runtime and CLI requirements

pnpm 11 requires Node.js 22 or newer and is pure ESM. The standalone binary also requires glibc 2.27 or newer. After upgrading, run pnpm setup because global binaries live under PNPM_HOME/bin.

Package scripts named clean, setup, deploy, or rebuild shadow pnpm's built-ins. Invoke a built-in explicitly with pnpm pm <name>.

Replace legacy build controls

Use allowBuilds as the unified dependency-build permission map:

allowBuilds:
  esbuild: true
  core-js: false

pnpm 11 rejects the older allow/deny settings. Use pnpm ignored-builds to inspect skipped scripts and pnpm approve-builds to record decisions. Keep strictDepBuilds enabled unless the project deliberately accepts unreviewed build scripts.

Expect stricter installation defaults

The current defaults include:

• a one-day minimumReleaseAge;
• blocked exotic transitive sources;
• failure on unreviewed dependency builds;
• optimistic repeat installs; and
• dependency verification before scripts.

Set minimumReleaseAge: 0 only as an explicit opt-out. Do not weaken integrity, patch-path, Git-SHA, alias-traversal, or build-script checks merely to make an install pass.

High-Value Workflows

Preview or reproduce an installation

Use pnpm install --dry-run to resolve and report changes without writing the manifest, lockfile, or node_modules.

Use pnpm ci for a clean workspace install with a frozen lockfile. A frozen CI install fails on an incompatible or absent root lockfile; fix or regenerate it outside the frozen operation.

For an intentionally read-only, prepopulated store, combine --frozen-store --offline --frozen-lockfile and satisfy the documented Node.js minor-version requirements.

Manage project runtimes

Declare Node.js, Deno, or Bun under devEngines.runtime. Installation resolves the requested range, locks the exact runtime and checksum, and uses that runtime for project scripts.

Use pnpm runtime set <name> <version> for development runtimes, or --save-prod for engines.runtime. Use pnpm install --no-runtime to skip fetching a lockfile-managed runtime without deleting its lockfile entry.

Configure workspaces in one place

Use camelCase settings in pnpm-workspace.yaml. The file may contain settings without a packages key. Project-level pnpm config set writes there when no project .npmrc exists.

Use catalogs when projects must share dependency ranges:

• catalogMode: strict rejects requested versions outside the catalog range.
• catalogMode: prefer uses a compatible catalog entry and otherwise falls back to a direct specifier.
• catalogMode: manual leaves catalog selection explicit.
• catalogPrune removes unused catalog entries during installation.

Keep dependency builds explicit

For one command, use --allow-build=<package>. Current releases persist that decision in allowBuilds. Use pnpm approve-builds --all only when blanket approval is intended and has been reviewed.

Git dependencies require repository-aware approval for prepare/build scripts. An ordinary package-name rule does not approve a Git-hosted artifact.

Diagnose dependency and environment state

• pnpm list --lockfile-only inspects the expected graph without installing.
• pnpm why <package> shows reverse paths from the package to workspace roots.
• pnpm peers check finds lockfile peer issues.
• pnpm audit signatures verifies installed registry signatures.
• pnpm doctor --json checks installation, paths, store/cache access, link strategies, registry access, and an offline local-package install.
• pnpm cache path prints the metadata-cache directory for CI caching.

Publish with the intended trust boundary

Use pnpm pack --dry-run to inspect package contents. A beforePacking hook may alter only the published manifest, while --skip-manifest-obfuscation retains package-manager metadata and publish lifecycle scripts.

Use atomic batch publishing only when the registry implements pnpm's batch endpoint. Use staged publishing when a version must remain hidden until an approval step.

Generate an SBOM with pnpm sbom and choose CycloneDX or SPDX deliberately. Use --lockfile-only for the complete platform-independent graph, --exclude-peers to omit peer-only trees, and --split for one file per workspace package.

Manage releases and dependency updates

Use pnpm change to write release intents and pnpm version -r to consume them. Check fixed groups, dependent propagation, release lanes, epic major-version bands, changelog storage, and the consumption ledger before automating publication.

When updating dependencies:

• release-age and trust policy can constrain candidates;
• explicit versions may move compatible catalog resolutions;
• resolutionMode still controls lowest/time-based selection;
• --changeset can generate release intents for affected workspaces; and
• GitHub Actions updates require the explicit non-interactive opt-in.

Safety Checks

Before accepting a lockfile or supply-chain change:

• Investigate checksum changes; --update-checksums is a narrow, explicit acceptance mechanism, not a routine recovery flag.
• Require 40-character Git commit SHAs in lockfile resolutions.
• Keep patch paths inside the patched package directory.
• Reject dependency aliases with path traversal.
• Keep authentication destination-bound and out of project configuration when the setting is global-only.
• Treat trustLockfile: true as a reviewed-lockfile policy decision.
• Do not assume an optional dependency softens trust-policy failures.

Output and Automation Notes

pnpm sends command-script banners and reporter output from store and config commands to stderr so stdout remains pipe-friendly. A non-recursive pnpm run --no-bail continues matching scripts but exits nonzero if any fail. Recursive empty version plans print [] with --json.

Use pnpm run "/pattern/" to select scripts by regular expression and --sequential when execution order or resource limits require concurrency one.

When Guidance Conflicts with a Repository

Prefer pinned project behavior and reproduce it locally. Check the exact pnpm binary selected by the project, because packageManager switching, devEngines.packageManager, pnpm with, and pmOnFail can select different CLIs. Apply only settings supported by that selected major version.