pnpm vs npm

Las diferencias prácticas entre pnpm y npm — cómo instalan paquetes, gestionan el espacio en disco, manejan lockfiles, y cuándo elegir uno u otro.

Recipe

Tarjeta de receta de referencia rápida — lista para copiar y pegar.

# Instalar pnpm (requiere Node.js 18.12+)
corepack enable
corepack prepare pnpm@latest --activate
 
# O instalar vía npm
npm install -g pnpm
 
# Verificar
pnpm --version
 
# Comandos comunes — lado a lado
npm install           # pnpm install
npm install react     # pnpm add react
npm install -D vitest # pnpm add -D vitest
npm uninstall react   # pnpm remove react
npm run dev           # pnpm dev  (o pnpm run dev)
npm test              # pnpm test
npx create-next-app   # pnpm create next-app  (o pnpm dlx create-next-app)

Cuándo usarlo: Cuando inicies un nuevo proyecto o evalúes si cambiar de npm a pnpm. Entender los tradeoffs te ayuda a tomar una decisión informada en lugar de cambiar por hype.

Deep Dive

Cómo npm instala paquetes

npm usa una estructura node_modules plana. Cuando ejecutas npm install, hace lo siguiente:

1. Lee package.json para las dependencias directas.
2. Resuelve el árbol completo de dependencias (dependencias de dependencias).
3. Eleva tantos paquetes como sea posible al nivel superior de node_modules/ para reducir duplicación.
4. Escribe package-lock.json para fijar versiones exactas.

node_modules/
  react/
  react-dom/
  scheduler/        # dependencia de react-dom, elevada al nivel superior
  loose-envify/     # dependencia transitiva, también elevada

El problema con la elevación: tu código puede hacer import de paquetes que no están en tu package.json porque resulta que están elevados. Esto se llama phantom dependencies — tu código funciona por accidente hasta que alguien elimina el paquete que trajo la dependencia transitiva.

Cómo pnpm instala paquetes

pnpm usa un almacén de contenido direccionable y symlinks. Cuando ejecutas pnpm install, hace lo siguiente:

1. Descarga paquetes a un almacén global (~/.local/share/pnpm/store/ en macOS/Linux).
2. Crea un almacén virtual dentro de node_modules/.pnpm/ con hard links al almacén global.
3. Crea symlinks en node_modules/ que apuntan solo a tus dependencias directas.

node_modules/
  react -> .pnpm/react@19.1.0/node_modules/react
  react-dom -> .pnpm/react-dom@19.1.0/node_modules/react-dom
  .pnpm/
    react@19.1.0/
      node_modules/
        react/          # hard link al almacén global
    react-dom@19.1.0/
      node_modules/
        react-dom/      # hard link al almacén global
        scheduler/      # symlink a .pnpm/scheduler@.../

Este layout significa:

• No puedes importar paquetes que no declaraste en package.json — sin phantom dependencies.
• Cada versión de un paquete se almacena una sola vez en disco en todos tus proyectos.
• node_modules es más pequeño e las instalaciones son más rápidas porque los archivos se vinculan, no se copian.

Diferencias clave

Ahorro de espacio en disco

Con npm, si tienes 10 proyectos que usan React 19, React se copia 10 veces. Con pnpm, React 19 se almacena una vez en el almacén global y se vincula mediante hard link en cada proyecto. En una máquina con muchos proyectos, pnpm puede ahorrar gigabytes de espacio en disco.

# Ver cuánto espacio está usando el almacén de pnpm
pnpm store status
 
# Limpiar paquetes no referenciados del almacén
pnpm store prune

Velocidad de instalación

pnpm es consistentemente más rápido que npm por varias razones:

• Hard links en lugar de copias de archivo.
• Descargas paralelas con solicitudes de red concurrentes.
• Almacén direccionable por contenido significa que los paquetes descargados previamente están disponibles instantáneamente.

Los benchmarks típicos muestran pnpm 2-3 veces más rápido que npm en instalaciones en frío y significativamente más rápido en instalaciones en caliente (cuando los paquetes ya están en el almacén).

Rigidez y seguridad

El layout estricto de node_modules de pnpm detecta errores reales:

// Esto funciona con npm (phantom dependency) pero falla con pnpm:
import chalk from 'chalk';
// Error: chalk no está listado en package.json

Si tu código solo funciona por la elevación de npm, pnpm expondrá la dependencia faltante inmediatamente. Esta es una característica, no un error — significa que tu package.json es una descripción precisa de lo que tu proyecto realmente usa.

Soporte de monorepo

Tanto npm como pnpm soportan workspaces, pero la implementación de pnpm es más madura:

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

# Ejecutar un comando en un workspace específico
pnpm --filter @myapp/web dev
 
# Instalar una dependencia en un workspace específico
pnpm --filter @myapp/web add zod
 
# Ejecutar un comando en todos los workspaces
pnpm -r build

El flag --filter de pnpm es más poderoso que el flag --workspace de npm, soportando patrones glob, filtrado basado en dependencias, y filtrado basado en cambios desde commit.

Comparación de comandos

Migrar de npm a pnpm

# 1. Instalar pnpm
corepack enable
corepack prepare pnpm@latest --activate
 
# 2. Eliminar artefactos de npm
rm -rf node_modules package-lock.json
 
# 3. Instalar con pnpm
pnpm install
 
# 4. (Opcional) Fijar la versión de pnpm en package.json
# Agregar: "packageManager": "pnpm@9.15.4"
 
# 5. Actualizar scripts — npm run -> pnpm
# Actualizar configuración de CI (GitHub Actions, etc.)

La migración es generalmente indolora. Si falla, casi siempre se debe a phantom dependencies — paquetes que tu código importa pero que faltan en package.json. Corrígelas agregando explícitamente los paquetes faltantes.

Cuándo usar npm

• Quieres cero configuración. npm se envía con Node.js. Nada extra que instalar.
• Estás siguiendo un tutorial. La mayoría de tutoriales y documentación usan comandos npm. Traducir a pnpm es trivial pero añade fricción al aprender.
• Tu equipo usa npm y no hay problemas. Cambiar package managers a mitad del proyecto tiene un costo. Si npm está funcionando bien, no hay razón urgente para cambiar.
• El almacenamiento en caché de CI ya está optimizado para npm. Algunos proveedores de CI tienen mejor almacenamiento en caché incorporado para node_modules y package-lock.json.

Cuándo usar pnpm

• Trabajas en muchos proyectos. El ahorro de espacio en disco es sustancial.
• Quieres corrección estricta de dependencias. Sin phantom dependencies significa menos sorpresas en producción.
• Ejecutas un monorepo. El soporte de workspace y filtrado de pnpm es de primera categoría.
• La velocidad de instalación importa. Instalaciones más rápidas significan CI más rápido e incorporación de desarrolladores más rápida.
• Quieres forzar un package manager específico. Corepack + "packageManager" en package.json asegura que todos usen la misma herramienta y versión.

Gotchas

1. Phantom dependencies se rompen en la migración. Si tu código importa un paquete que no está en package.json, funciona con npm pero falla con pnpm. La solución es agregar el paquete faltante a package.json — esto es lo correcto de todas formas.
2. Algunos paquetes asumen node_modules plano. Paquetes antiguos que usan trucos de require.resolve o suben el árbol de directorios pueden fallar con el layout vinculado mediante symlinks de pnpm. La solución alternativa es node-linker=hoisted en .npmrc, pero esto derrotaría la rigidez de pnpm.
3. El formato del lockfile es diferente. npm usa package-lock.json (JSON). pnpm usa pnpm-lock.yaml (YAML). No puedes usar ambos — elige uno y agrega el otro a .gitignore.
4. npx no existe en pnpm. Usa pnpm dlx en su lugar. Ejemplo: pnpm dlx create-next-app en lugar de npx create-next-app.
5. Rigidez de peer dependencies. pnpm es más estricto sobre peer dependencies que npm. Si un paquete espera react como peer dependency y no la has instalado, pnpm advierte o genera error. Soluciona instalando la peer dependency.
6. La configuración de CI es diferente. GitHub Actions y otros proveedores de CI necesitan pnpm/action-setup o Corepack para instalar pnpm antes de ejecutar pnpm install.
7. Ubicación del almacén global. El almacén global de pnpm puede crecer bastante con el tiempo. Ejecuta pnpm store prune periódicamente para limpiar paquetes que ya no son referenciados por ningún proyecto.

Alternativas

FAQs

Related

• Installing Node.js and npm
• Running Node.js Scripts in JavaScript
• ESM vs CommonJS Modules