Nếu bạn đang dùng npm cho dự án Node.js và muốn chuyển sang pnpm, tin tốt là việc này không xung đột với nvm. Hai công cụ này quản lý hai lớp khác nhau: nvm quản lý phiên bản Node.js trên máy, còn pnpm quản lý package trong từng dự án.

Bài này hướng dẫn cách chuyển từ npm sang pnpm theo cách thực tế, dễ rollback, phù hợp cho cả dự án cá nhân lẫn team nhỏ.

Vì sao nên cân nhắc pnpm?

pnpm là package manager cho Node.js giống như npm, nhưng có kiến trúc lưu dependency khác. Thay vì sao chép toàn bộ package vào từng dự án, pnpm lưu package trong một store chung trên máy và tạo liên kết vào thư mục node_modules của từng project. Cách này thường giúp tiết kiệm dung lượng ổ đĩa và cài đặt nhanh hơn khi bạn làm nhiều dự án.

Điểm đáng giá hơn là pnpm quản lý dependency chặt hơn. Với npm, do cấu trúc node_modules thường được làm phẳng, bạn có thể vô tình import một package mà dự án chưa khai báo trực tiếp trong package.json. Đây hay được gọi là phantom dependencies. Với pnpm, dự án chỉ nên dùng những package đã khai báo rõ, nên lỗi thiếu dependency dễ lộ ra sớm hơn.

Dùng nvm có ảnh hưởng gì không?

Không. Bạn vẫn dùng nvm bình thường để đổi phiên bản Node.js:

nvm use 20
nvm use 22

Sau đó bạn dùng pnpm trong project như bình thường. Điểm cần lưu ý là cách cài pnpm. Nếu bạn cài bằng npm install -g pnpm, mỗi phiên bản Node do nvm quản lý có thể có bộ global package riêng. Khi đổi Node version, bạn có thể thấy lệnh pnpm bị mất hoặc khác phiên bản.

Cách gọn hơn là dùng Corepack. Theo tài liệu pnpm, Node.js có Corepack để quản lý package manager như pnpm. Tài liệu Node.js cũng mô tả Corepack là công cụ cung cấp proxy binary cho package manager và tự chạy đúng package manager đã cấu hình trong project.

Bước 1: Kiểm tra phiên bản Node đang dùng

Trước tiên, kiểm tra Node:

node -v

Nếu bạn dùng Node 22 trở lên, bạn có thể dùng pnpm đời mới nhất. Nếu đang ở Node 18 hoặc 20, nên pin pnpm ở phiên bản còn hỗ trợ Node của bạn, thay vì mặc định kéo bản quá mới. Lý do là pnpm 11 đã yêu cầu Node.js 22 trở lên theo thông báo phát hành chính thức của pnpm.

Ví dụ, đổi sang Node 22 bằng nvm:

nvm install 22
nvm use 22

Bước 2: Bật Corepack và kích hoạt pnpm

Với Node hiện đại, bạn có thể bật Corepack:

corepack enable

Sau đó kích hoạt pnpm. Nếu bạn đang dùng Node 22 trở lên:

corepack prepare pnpm@latest --activate

Hoặc nếu muốn pin theo major ổn định đang dùng trong dự án:

corepack use pnpm@latest-11

Nếu bạn đang ở Node 18 hoặc 20, hãy dùng phiên bản pnpm phù hợp với project của bạn, ví dụ:

corepack prepare pnpm@10 --activate

Kiểm tra lại:

pnpm -v

Bước 3: Chuyển project từ npm sang pnpm

Đi vào thư mục dự án đang dùng npm:

cd ten-du-an-cua-ban

Nếu project đang có package-lock.json, pnpm có lệnh import để tạo pnpm-lock.yaml từ lockfile của npm. Tài liệu chính thức của pnpm ghi rõ pnpm import có thể tạo pnpm-lock.yaml từ package-lock.json, npm-shrinkwrap.json hoặc yarn.lock.

pnpm import

Sau đó xoá thư mục dependency cũ và lockfile npm:

rm -rf node_modules
rm package-lock.json

Cài lại bằng pnpm:

pnpm install

Theo tài liệu pnpm, pnpm install dùng để cài tất cả dependency của project và có alias ngắn là pnpm i.

Bước 4: Chạy thử project

Chạy các script cũ trong package.json. Với pnpm, bạn có thể chạy ngắn hơn:

pnpm dev
pnpm build
pnpm test

Nếu trước đây bạn chạy:

npm run dev

Thì khi dùng pnpm thường có thể chạy:

pnpm dev

Các lệnh npm và pnpm thường dùng

  • Cài tất cả dependency: npm install đổi thành pnpm install hoặc pnpm i.
  • Thêm package mới: npm install ten-goi đổi thành pnpm add ten-goi.
  • Thêm dev dependency: npm install -D ten-goi đổi thành pnpm add -D ten-goi.
  • Gỡ package: npm uninstall ten-goi đổi thành pnpm remove ten-goi.
  • Chạy script: npm run dev đổi thành pnpm dev.
  • Chạy package tạm thời: npx create-vite có thể đổi thành pnpm dlx create-vite.

Nên commit những file nào?

Sau khi chuyển xong, bạn nên commit:

  • package.json, nếu có thay đổi script hoặc khai báo package manager.
  • pnpm-lock.yaml.
  • pnpm-workspace.yaml, nếu đây là monorepo.

Không commit node_modules. Nếu team đang dùng chung project, nên thống nhất package manager trong README hoặc trong trường packageManager của package.json để tránh người này dùng npm, người kia dùng pnpm.

Lỗi thường gặp khi chuyển sang pnpm

1. Lệnh pnpm không tồn tại sau khi đổi Node bằng nvm

Hãy bật lại Corepack trong phiên bản Node đang dùng:

corepack enable
pnpm -v

2. Project báo thiếu dependency dù trước đây npm vẫn chạy

Đây thường là dấu hiệu project đang dùng phantom dependency. Cách sửa đúng là thêm package đó vào package.json:

pnpm add ten-goi-bi-thieu

3. Monorepo import lockfile chưa đúng

Nếu project là monorepo, tài liệu pnpm lưu ý rằng workspace cần được khai báo trong pnpm-workspace.yaml trước khi import dependency. Ví dụ:

packages:
  - "apps/*"
  - "packages/*"

Quy trình chuyển nhanh

Nếu chỉ cần checklist ngắn, bạn có thể làm theo thứ tự này:

node -v
corepack enable
corepack prepare pnpm@10 --activate
pnpm -v
pnpm import
rm -rf node_modules
rm package-lock.json
pnpm install
pnpm dev

Nếu bạn đang dùng Node 22 trở lên, có thể thay dòng corepack prepare pnpm@10 --activate bằng phiên bản pnpm mới hơn, ví dụ pnpm@latest hoặc version mà team đã thống nhất.

Kết luận

Chuyển từ npm sang pnpm không khó, kể cả khi bạn đang dùng nvm. Cách làm sạch nhất là để nvm quản lý Node, dùng Corepack để quản lý pnpm, import lockfile cũ bằng pnpm import, rồi cài lại dependency bằng pnpm install.

Với dự án nhỏ, lợi ích dễ thấy nhất là cài package gọn và nhanh hơn. Với team hoặc monorepo, lợi ích lớn hơn là dependency rõ ràng, lockfile nhất quán và ít lỗi ngầm do dùng nhầm package chưa khai báo.

Tài liệu tham khảo