How to Migrate from npm to pnpm

Package management is a crucial aspect of modern JavaScript development. While npm has long been the default package manager for Node.js projects, pnpm has gained significant popularity due to its efficiency, disk space savings, and improved dependency management. In this guide, I'll walk you through migrating your projects from npm to pnpm with minimal hassle.

What is pnpm?

pnpm (performant npm) is a fast, disk space efficient package manager that uses a unique approach to managing dependencies. Unlike npm or Yarn, which create copies of packages in each project's node_modules directory, pnpm uses a content-addressable store and creates hard links or symlinks to the packages. This approach has several advantages:

• Disk space efficiency: Each package is stored only once on your disk
• Faster installations: No need to copy packages for each project
• Strict dependency management: Prevents accessing packages not explicitly listed as dependencies

Prerequisites

Before migrating to pnpm, ensure you have:

• Node.js installed (version 14.x or later recommended)
• Access to modify your project's configuration

Installation

First, you need to install pnpm globally:

npm install -g pnpm

Alternatively, you can use the recommended installation methods:

For Windows (PowerShell):

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

For macOS/Linux:

curl -fsSL https://get.pnpm.io/install.sh | sh -

Step-by-Step Migration Process

1. Remove existing npm lock files and node_modules

Start by removing npm's lock file and the node_modules directory:

rm package-lock.json
rm -rf node_modules

2. Convert npm scripts to pnpm

If your project uses npm scripts in package.json, you can keep using them. pnpm supports the same commands with the same syntax, just replace npm with pnpm:

• npm install → pnpm install
• npm run dev → pnpm dev
• npm run build → pnpm build
• npm test → pnpm test

3. Install dependencies with pnpm

Reinstall your dependencies using pnpm:

pnpm install

This command will:

• Read your package.json file
• Install all dependencies
• Generate a pnpm-lock.yaml file (equivalent to package-lock.json)

4. Configure pnpm

Create a .npmrc file in your project root to configure pnpm:

shamefully-hoist=true
strict-peer-dependencies=false

The shamefully-hoist option helps with compatibility for applications that expect a flat node_modules structure. You can remove this once your project is fully compatible with pnpm's default directory structure.

5. Update CI/CD pipelines

If you're using CI/CD pipelines, update your configuration files:

GitHub Actions example:

- name: Install dependencies
run: |
  npm install -g pnpm
  pnpm install

CircleCI example:

- run:
  name: Install dependencies
  command: |
    npm install -g pnpm
    pnpm install

6. Update your README.md

Update your project documentation to reflect the switch to pnpm:

## Development

This project uses pnpm for dependency management.

### Install dependencies
```bash
pnpm install
```

### Start development server
```bash
pnpm dev
```

Common Issues and Solutions

Missing dependencies

If you encounter errors about missing dependencies, try using the --shamefully-hoist flag:

pnpm install --shamefully-hoist

Incompatible packages

Some packages may not be compatible with pnpm's node_modules structure. In such cases:

1. Add the problematic package to the .pnpmfile.cjs file:

function readPackage(pkg) {
if (pkg.name === 'problematic-package') {
  // Fix the package configuration
}
return pkg;
}

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

2. Or use the public-hoist-pattern in your .npmrc file:

public-hoist-pattern[]=*problematic-package*

Benefits of Using pnpm

After migrating, you'll enjoy several benefits:

1. Faster installation: pnpm is significantly faster than npm, especially on CI systems
2. Disk space efficiency: Save gigabytes of space across multiple projects
3. Stricter dependency resolution: Avoid "phantom dependencies" issues
4. Workspace support: Better monorepo management with built-in workspace features
5. Improved security: Better protection against supply chain attacks due to stricter dependency isolation

Conclusion

Migrating from npm to pnpm is a straightforward process that can significantly improve your development workflow. While there might be a few compatibility issues to solve initially, the long-term benefits in terms of performance, disk space usage, and dependency management make it well worth the effort.

Have you migrated your projects to pnpm? Share your experience and any tips you discovered along the way!