npm to pnpm Migration

Overview

Migrate existing npm projects to pnpm. Covers single packages, workspaces/monorepos, CI/CD configuration, and common migration issues.

Current pnpm version: 10.28 (January 2026) - See version_info.md for details.

Quick Start (Single Package)

1. Install pnpm

npm install -g pnpm

2. Remove npm artifacts

rm package-lock.json rm -rf node_modules

3. Generate pnpm lockfile

pnpm import

4. Install dependencies

pnpm install

5. Verify

pnpm test && pnpm build

Workflow Decision Tree

Is this a single package or workspace/monorepo?

• Single package: Use workflow_single_package.md

• Workspace/monorepo: Use workflow_workspace_monorepo.md

Experiencing issues after migration?

• Module not found: See troubleshooting.md

• Module Resolution Issues

• Build fails: See troubleshooting.md

• Build and Tooling Issues

• CI fails: See troubleshooting.md

• CI/CD Issues

• Other issues: See troubleshooting.md

Need npm command equivalents?

• See cli_reference.md for all command translations

Core Migration Steps

1. Install pnpm

See installation.md for all installation methods. Quick options:

Via npm

npm install -g pnpm

Via standalone script (recommended)

curl -fsSL https://get.pnpm.io/install.sh | sh -s -- --version=10.28.0

Windows PowerShell

iwr https://get.pnpm.io/install.ps1 -useb | iex

2. Convert Lockfile

Use pnpm import to convert package-lock.json or yarn.lock to pnpm-lock.yaml :

pnpm import

See import_command.md for details on import behavior and workspace considerations.

3. Install Dependencies

pnpm install

Key flags:

• --frozen-lockfile

• CI mode, exact install from lockfile

• --shamefully-hoist

• Temporarily work around module resolution issues

• --force

• Regenerate lockfile from package.json

See install_command.md for full install options.

4. Update Scripts

npm → pnpm command changes:

npm pnpm

npm run <script>

pnpm <script> or pnpm run <script>

npm install <pkg>

pnpm add <pkg>

npm install -D <pkg>

pnpm add -D <pkg>

npm uninstall <pkg>

pnpm remove <pkg>

npx <cmd>

pnpm exec <cmd> or pnpm dlx <cmd>

See cli_reference.md for complete command reference.

Workspaces and Monorepos

npm workspaces require different handling:

• Create pnpm-workspace.yaml to define workspace packages

• Change workspace dependencies from * to workspace:* protocol

• Update scripts to use pnpm -r instead of npm --workspaces

Full guide: workflow_workspace_monorepo.md

Key Differences to Understand

Module Structure

pnpm uses a content-addressable store with symlinks, not a flat node_modules . This:

• Saves disk space (packages stored once globally)

• Creates stricter dependency resolution (reveals hidden dependencies)

• May require explicit dependency declarations

Lockfile

npm ignores package-lock.json . Use pnpm import to convert. After conversion, commit pnpm-lock.yaml to version control.

See limitations.md for details on lockfile differences.

Common Migration Gotchas

Missing Dependencies

Symptom: "Cannot find module" errors after migration

Cause: pnpm's strict layout reveals packages that were "accidentally" available in npm

Solution:

pnpm add <missing-package>

Workspace Protocol

npm: "my-utils": "*"

pnpm: "my-utils": "workspace:*"

Lifecycle Scripts

pnpm may run pre/post scripts differently. If needed:

.npmrc

enable-pre-post-scripts=true

CI/CD Updates

Update your CI to use pnpm:

GitHub Actions:

• uses: pnpm/action-setup@v4 with: version: 10.28.0
• uses: actions/setup-node@v4 with: cache: 'pnpm'

See workflow_single_package.md for more CI examples.

Reference Files Index

Workflow Guides

• workflow_single_package.md

• Standalone package migration

• workflow_workspace_monorepo.md

• Workspace and monorepo migration

• troubleshooting.md

• Common issues and solutions

Command Reference

• cli_reference.md

• npm → pnpm command translation

• install_command.md

• Full pnpm install documentation

• add_command.md

• Dependency adding options

• import_command.md

• Lockfile conversion details

Documentation

• version_info.md

• Current version (10.28) and installation

• installation.md

• All installation methods

• limitations.md

• Known pnpm limitations

• workspaces.md

• Full workspace documentation

• npm_vs_pnpm.md

• Feature comparison

• release_10.28.md

• Latest release notes

• releases.md

• Full release history

Configuration (.npmrc)

Common settings for npm migrants:

Temporary migration aids

shamefully-hoist=true auto-install-peers=true

Strictness settings

strict-peer-dependencies=false enable-pre-post-scripts=true

Migration Checklist

• Install pnpm globally

• Remove package-lock.json

• Run pnpm import

• Run pnpm install

• Verify tests pass

• Verify build succeeds

• Update CI/CD configuration

• Update documentation/README

• Update team on command changes

• Commit pnpm-lock.yaml

When NOT to Use pnpm

Consider staying with npm if:

• Project relies on npm-specific features (npx quirks, flat modules)

• Legacy tooling with hardcoded node_modules paths

• Strict requirements for npm compatibility

• See limitations.md for full details