pnpm migration
Última actualización

Migración de npm a pnpm

Una guía clara, paso a paso, para migrar cualquier proyecto Node.js de npm a pnpm sin fricción.

!
Antes de empezar

Asegurate de tener Node.js ≥ 18.17 instalado en tu máquina.

Atajo

¿El repo ya está migrado?

Si los archivos de configuración (.npmrc, pnpm-workspace.yaml, pnpm-lock.yaml) ya están commiteados, no necesitás recrear nada.

  1. Paso 1 — Instalar pnpm en tu máquina
  2. Paso 2 — Limpiar artefactos de npm
  3. Instalar dependencias desde el lockfile
  4. Paso 7 — Build de verificación
bash 
git pull
pnpm install
pnpm run build

Podés saltearte los pasos 3, 5 y 6 — esos modifican archivos que ya están en el repo.

01

Instalar pnpm

Descargá e instalá pnpm con el script oficial. Después recargá tu shell para que el binario quede en el PATH.

bash 
curl -fsSL https://get.pnpm.io/install.sh | sh -
source ~/.bashrc
¿Usás zsh o fish? Reemplazá ~/.bashrc por ~/.zshrc o el archivo de config que corresponda.
02

Limpiar el repo

Borrá todos los artefactos generados por npm para que pnpm arranque desde cero.

bash 
rm -rf node_modules/
rm package-lock.json
Si tu framework genera caché propia (ej: .next/, dist/, build/, .cache/), borrala también para evitar artefactos viejos.
03

Configurar .npmrc

Creá o editá el archivo .npmrc en la raíz del repo:

.npmrc 
shamefully-hoist=true
¿Por qué? pnpm usa un node_modules estricto por defecto. Algunos paquetes asumen el hoisting plano de npm y rompen sin esta flag. Es la solución compatible mientras tu proyecto se adapta.
04

Instalar dependencias

Una vez limpio el repo y configurado .npmrc, ejecutá:

bash 
pnpm install

pnpm va a leer tu package.json, descargar todas las dependencias declaradas y generar un pnpm-lock.yaml nuevo. Ese lockfile reemplaza al package-lock.json que borraste — commiteá el nuevo lockfile al repo.

05

Equivalencias npm → pnpm

Tus scripts del package.json no cambian. Lo único que cambia es cómo los invocás desde la terminal:

npm
pnpm
npm install
pnpm install
npm install <pkg>
pnpm add <pkg>
npm install -D <pkg>
pnpm add -D <pkg>
npm uninstall <pkg>
pnpm remove <pkg>
npm run <script>
pnpm <script>
npm ci
pnpm install --frozen-lockfile
npx <cli>
pnpm dlx <cli>

Opcionalmente, fijá la versión de pnpm que usa el equipo agregando este campo al package.json:

package.json 
"packageManager": "pnpm@9.0.0"
06

Aprobar build scripts

Por seguridad, pnpm bloquea los scripts de postinstall de paquetes terceros. Al instalar, vas a ver una lista de paquetes bloqueados — necesitás aprobar explícitamente los que requieran compilar binarios o generar código.

La forma más simple es ejecutar el comando interactivo:

bash 
pnpm approve-builds

O declarar la lista en pnpm-workspace.yaml en la raíz del repo (recomendado para tener el listado versionado):

pnpm-workspace.yaml 
allowBuilds:
  esbuild: true
  sharp: true
  # <paquete>: true   → aprobar postinstall
  # <paquete>: false  → ignorar postinstall
Este listado depende de tu proyecto. Corré pnpm install primero — pnpm te va a mostrar exactamente qué paquetes necesitan aprobación según las dependencias que tengas.

Después de configurar, reinstalá:

bash 
pnpm install
07

Build de verificación

Validá que todo compila end-to-end con tu script de build:

bash 
pnpm run build
✓
Si el build pasa, la migración está lista.

Tu repo ahora corre 100% sobre pnpm. Commiteá pnpm-lock.yaml, .npmrc y pnpm-workspace.yaml y abrí el PR.

08

Next.js: 14 vs 16

Si tu proyecto usa Next.js, la versión cambia algunos requisitos de la migración. Estas son las diferencias que más impactan al pasar a pnpm:

Next.js 14
Next.js 16
Node.js mínimo
≥ 18.17
≥ 20.9
React
18
19
Bundler por defecto
Webpack
Turbopack
Lanzamiento
Oct 2023
Oct 2025
Next.js 16 deja de soportar Node 18. El mínimo sube a Node 20.9 (Node 18 llegó a end-of-life). Actualizá Node antes de correr pnpm install para evitar el error de versión que verás en Troubleshooting.
En ambas versiones, Next usa sharp para optimizar imágenes — es un binario nativo, así que acordate de aprobar su build script en el paso 06.
09

Troubleshooting

Si algo no funciona, revisá estos casos antes de pedir ayuda.

Error Aparece ERR_PNPM_IGNORED_BUILDS
Significa que pnpm encontró un paquete con script de postinstall que no está declarado en pnpm-workspace.yaml. Revisá el archivo y agregá el paquete con true o false según corresponda. También podés correr pnpm approve-builds para resolverlo interactivamente.
Warning Falla algún paquete por hoisting
Confirmá que el .npmrc en la raíz tenga la línea shamefully-hoist=true. Si lo agregaste después de instalar, borrá node_modules/ y volvé a correr pnpm install.
Error Node version error
Necesitás Node ≥ 18.17. Actualizá con nvm install 18.17 (o más reciente), después nvm use y volvé a correr pnpm install.
Warning pnpm no se encuentra después de instalar
El binario quedó instalado pero tu shell todavía no lo ve. Cerrá y reabrí la terminal, o ejecutá source ~/.bashrc (o ~/.zshrc). Verificá con pnpm -v.