Migración de npm a pnpm

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

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.

Migración de npm a pnpm

¿El repo ya está migrado?