How to migrate a project from npm to pnpm

Migrating projects from npm to pnpm is an effective method to enhance package management efficiency and reduce disk space usage. Below is a detailed step-by-step guide:

1. Install pnpm

First, install pnpm on your machine using the following command:

bash
npm install -g pnpm

2. Prepare for Migration

Before migrating, ensure your current project is functioning properly under npm, including running tests and verifying all dependencies are up to date. This allows you to compare behavior before and after migration to confirm no issues were introduced.

3. Delete node_modules and package-lock.json

pnpm uses a different approach to install and link dependencies, so delete the existing node_modules folder and package-lock.json or npm-shrinkwrap.json file (if present):

bash
rm -rf node_modules package-lock.json

4. Install Dependencies with pnpm

Now use pnpm to install your project dependencies. Run the following command in your project root directory:

bash
pnpm install

This installs all dependencies declared in package.json and generates a pnpm-lock.yaml file, similar to npm's package-lock.json but tailored for pnpm.

5. Test the Project

After installation, run the project's test and build scripts to verify everything works as expected. Execute:

bash
pnpm run test
pnpm run build
# or other relevant scripts

If dependency-related issues occur, check and update dependency declarations in package.json to match those in pnpm-lock.yaml.

6. Update CI/CD Scripts

If your project uses continuous integration/continuous deployment (CI/CD), update relevant scripts to use pnpm commands instead of npm commands.

For example, modify .travis.yml, Jenkinsfile, GitLab-CI.yml, and similar configuration files.

7. Commit Changes

Commit these changes to your version control system:

bash
git add pnpm-lock.yaml
git commit -m "Migrate from npm to pnpm"

Ensure the node_modules folder is not committed, as it should typically be excluded in .gitignore.

8. Notify Team Members

If working in a team, notify all members to switch to pnpm. Provide installation steps and common post-migration issues.

9. Monitor Production Environment

If deploying the migrated project to production, closely monitor the application to ensure no migration-related issues arise. If problems occur, quickly identify the root cause using logs and metrics, then resolve them.

This is a basic guide for migrating projects from npm to pnpm. The actual process may vary based on project specifics, such as dependency complexity and automation script usage.