pnpm 10: el gestor de paquetes de Node.js con enlaces simbólicos

Introducción

⏱️ Lectura: 12 min

Si alguna vez clonaste un proyecto de JavaScript y viste cómo node_modules crecía hasta los cientos de megabytes, sabés que algo no cuadra. Un proyecto vacío recién iniciado puede ocupar fácilmente entre 200 y 500 MB. Multiplicá eso por diez repositorios en tu máquina y ya hablamos de gigabytes duplicados una y otra vez. En ese contexto apareció pnpm, un gestor de paquetes para Node.js que replantea cómo se almacenan las dependencias en disco.

📑 En este artículo

1. Introducción
2. Qué es pnpm
3. Cómo funciona pnpm por dentro
   1. El almacén global (content-addressable store)
   2. Enlaces duros y simbólicos
   3. Diagrama del flujo
4. Instalación paso a paso
   1. En Linux y macOS
   2. En Windows
   3. Usando Corepack (recomendado para proyectos)
5. Comandos esenciales del día a día
   1. Alias corto: pn
6. Casos de uso reales
   1. Monorepos con pnpm workspaces
   2. CI/CD más rápido
   3. Laptops y máquinas con espacio limitado
7. Ventajas y desventajas
   1. Ventajas
   2. Desventajas
8. Preguntas frecuentes
   1. ¿pnpm es compatible con npm y yarn?
   2. ¿Puedo usar pnpm en producción y en Docker?
   3. ¿Qué pasa si borro el almacén global?
   4. ¿pnpm funciona con TypeScript, Next.js, Vite, etc.?
   5. ¿Cuál es la diferencia con yarn berry (Plug’n’Play)?
   6. ¿Vale la pena migrar un proyecto grande desde npm?
9. Referencias
   1. 📚 Artículos relacionados

Durante años, npm y yarn se pelearon por ser el estándar del ecosistema. Ambos copian cada paquete una vez por proyecto, lo que genera duplicación masiva y tiempos de instalación largos. pnpm (que significa performant npm) tomó otra ruta: un almacén global único en tu máquina más enlaces simbólicos en cada proyecto. El resultado es instalaciones más rápidas, menos espacio ocupado y, como bonus, un árbol de dependencias más estricto que detecta errores sutiles que npm deja pasar.

En esta guía completa vas a entender qué es pnpm, cómo funciona por dentro, cómo instalarlo en Windows, macOS y Linux, qué comandos usar en el día a día, y cuándo realmente conviene migrar desde npm o yarn. Si trabajás en un equipo con monorepos, CI/CD lentos o laptops con SSDs chicos, este artículo te va a interesar.

Qué es pnpm

pnpm es un gestor de paquetes alternativo para el ecosistema de Node.js, compatible con el mismo package.json y el mismo registro de npm (registry.npmjs.org). Fue creado en 2016 por Zoltan Kochan y hoy, en su versión 10.x, es adoptado por proyectos grandes como Vue, Vite, Prisma, Svelte y el propio Next.js en algunos de sus ejemplos.

A diferencia de npm o yarn, pnpm no copia cada dependencia dentro de node_modules. En su lugar, guarda una sola copia de cada paquete (y de cada versión) en un almacén global ubicado en tu carpeta de usuario, y después crea enlaces duros y simbólicos hacia ese almacén desde cada proyecto. La metáfora más clara: es como tener una biblioteca central con todos los libros, y en cada proyecto colocás un estante con etiquetas que apuntan al libro original, en lugar de fotocopiarlo cada vez.

Esto tiene tres consecuencias prácticas enormes. Primero, el disco deja de llenarse con copias redundantes: tener [email protected] en 50 proyectos ocupa el espacio de una sola instalación. Segundo, las instalaciones son significativamente más rápidas porque no hay que bajar ni descomprimir paquetes que ya existen en el almacén. Y tercero, el árbol de node_modules queda estricto: tu código solo puede importar paquetes que declaraste explícitamente en package.json, no dependencias transitivas «por accidente».

Cómo funciona pnpm por dentro

La arquitectura de pnpm se basa en dos ideas clave: el content-addressable store (CAS) y los enlaces simbólicos estructurados. Entender estas dos piezas te ayuda a diagnosticar problemas, optimizar tu CI y sacarle más provecho a la herramienta.

El almacén global (content-addressable store)

El primer truco de pnpm es guardar cada archivo identificado por su hash de contenido. Es decir, no se almacena «la carpeta lodash«, sino archivos individuales indexados por un hash SHA. Si dos versiones distintas de dos paquetes tienen el mismo archivo (cosa habitual con LICENSE, README.md o scripts pequeños), se guarda una sola vez. Este almacén vive por defecto en ~/.local/share/pnpm/store en Linux, %LOCALAPPDATA%/pnpm/store en Windows y ~/Library/pnpm/store en macOS.

Enlaces duros y simbólicos

Cuando corrés pnpm install, el gestor arma node_modules en dos capas. Los paquetes reales viven dentro de node_modules/.pnpm/ con nombres largos tipo [email protected], donde cada archivo es un hard link al almacén global. Luego, en la raíz de node_modules/, pnpm crea symlinks solo para los paquetes que declaraste en package.json. Así tu código nunca puede hacer require('lodash') si lodash no es dependencia directa — aunque otro paquete la tenga.

💭 Clave: esta estricta separación resuelve el «phantom dependencies problem» de npm: código que funciona en tu máquina pero rompe en producción porque dependía de un paquete que no estaba en tu package.json.

Diagrama del flujo

graph LR
 A["pnpm install"] --> B["Leer package.json"]
 B --> C["Resolver dependencias"]
 C --> D{"¿Ya está en el store?"}
 D -- "Sí" --> E["Crear hard link"]
 D -- "No" --> F["Descargar al store"]
 F --> E
 E --> G["Crear symlinks en node_modules"]
 G --> H["Proyecto listo"]

Instalación paso a paso

pnpm se instala de varias formas según tu sistema y preferencia. Para la versión 10.x necesitás Node.js 18.12 o superior, salvo que uses el binario standalone @pnpm/exe, que no requiere Node.js previo.

En Linux y macOS

# Opción 1: script oficial (instala pnpm sin Node.js si hace falta)
curl -fsSL https://get.pnpm.io/install.sh | sh -

# Opción 2: Homebrew (macOS o Linux con brew)
brew install pnpm

# Opción 3: vía npm existente
npm install -g pnpm@latest-10

# Verificar instalación
pnpm --version

En Windows

# Opción 1: PowerShell
Invoke-WebRequest https://get.pnpm.io/install.ps1 -UseBasicParsing | Invoke-Expression

# Opción 2: winget
winget install -e --id pnpm.pnpm

# Opción 3: Chocolatey
choco install pnpm

# Opción 4: Scoop
scoop install nodejs-lts pnpm

⚠️ Ojo: en Windows, Microsoft Defender puede ralentizar mucho la instalación de paquetes. Si notás que pnpm tarda más de lo esperado, excluí el almacén con: Add-MpPreference -ExclusionPath $(pnpm store path) en una PowerShell con permisos de administrador.

Usando Corepack (recomendado para proyectos)

Corepack viene con Node.js desde la versión 16.13 y te permite fijar la versión exacta del gestor de paquetes por proyecto. Es la forma más limpia si trabajás en equipo:

# Actualizar Corepack a la última versión
npm install --global corepack@latest

# Habilitar pnpm
corepack enable pnpm

# Fijar la versión en tu proyecto
corepack use pnpm@latest-10

El último comando agrega un campo "packageManager" en tu package.json, y desde ese momento todos los desarrolladores que usen Corepack van a correr exactamente la misma versión de pnpm. Cero discusiones de «en mi máquina funciona».

Comandos esenciales del día a día

La mayoría de los comandos de pnpm tienen una correspondencia directa con npm, así que la curva de aprendizaje es baja. Esta es la chuleta que usás en el 95% de los casos:

# Instalar todas las dependencias del proyecto
pnpm install         # o simplemente 'pnpm i'

# Agregar un paquete
pnpm add react
pnpm add -D typescript          # dependencia de desarrollo
pnpm add -g serve               # global

# Eliminar un paquete
pnpm remove lodash              # o 'pnpm rm lodash'

# Actualizar dependencias
pnpm update
pnpm update --latest            # ignora rangos de semver

# Ejecutar scripts del package.json
pnpm run dev                    # o 'pnpm dev'

# Ejecutar un binario sin instalarlo globalmente
pnpm dlx create-vite my-app     # equivalente a 'npx'

# Auditar vulnerabilidades
pnpm audit

# Ver qué paquetes están desactualizados
pnpm outdated

Alias corto: pn

Si escribir pnpm 200 veces al día te cansa, podés poner un alias. En Linux o macOS, agregá a tu .bashrc, .zshrc o config.fish:

alias pn=pnpm

Y listo: pn install, pn dev, pn add. Cada dos letras ahorradas se multiplican por cientos de invocaciones al mes.

Casos de uso reales

No todos los proyectos necesitan pnpm. Pero hay escenarios donde la diferencia es tan grande que cambiar se vuelve obvio.

Monorepos con pnpm workspaces

Este es el caso estrella. Si tenés un monorepo con varios paquetes (por ejemplo, apps/web, apps/mobile, packages/ui, packages/utils), pnpm lo maneja nativamente con un archivo pnpm-workspace.yaml:

packages:
  - 'apps/*'
  - 'packages/*'

Desde ese momento, podés correr pnpm install en la raíz y pnpm enlaza los paquetes internos entre sí sin publicarlos al registro. Herramientas como Turborepo o Nx trabajan muy bien sobre pnpm precisamente por su modelo de enlaces.

CI/CD más rápido

En GitHub Actions, GitLab CI o CircleCI, cachear el almacén de pnpm es mucho más eficiente que cachear node_modules. El almacén se comparte entre branches y entre proyectos, mientras que node_modules se invalida apenas cambiás una dependencia. Muchos equipos reportan reducciones del 40% al 70% en tiempos de instalación al migrar pipelines de npm ci a pnpm install --frozen-lockfile.

Laptops y máquinas con espacio limitado

Si tenés un MacBook Air con 256 GB o un Windows con SSD chico, la diferencia es brutal. Un desarrollador con 30 proyectos Node en su máquina puede pasar de usar 40 GB en node_modules a usar 4 GB con pnpm, porque las duplicaciones desaparecen.

Ventajas y desventajas

Ventajas

• Ahorro de disco masivo — una sola copia global por versión de paquete.
• Instalaciones más rápidas — sobre todo en proyectos ya cacheados.
• Árbol estricto — detecta dependencias fantasma antes de que lleguen a producción.
• Monorepos nativos — sin necesidad de lerna u otras herramientas externas.
• Compatibilidad total — usa el mismo registro y package.json que npm.
• Seguridad — pnpm 10 introdujo mitigaciones contra ataques de supply chain como scripts de instalación desactivados por defecto.

Desventajas

• Algunas herramientas viejas asumen que node_modules es plano y fallan con symlinks. Casos raros, pero existen (sobre todo bundlers legacy).
• Curva mental — entender por qué no podés importar un paquete transitivo lleva algo de tiempo.
• Windows Defender puede ralentizar la primera instalación si no excluís el almacén.
• Docker requiere configuración específica para aprovechar el caché (usar layers o multi-stage builds).

💡 Tip: si migrás un proyecto existente, corré pnpm install y después pnpm run build antes de commitear el nuevo pnpm-lock.yaml. Si algo se rompe, lo más probable es que estuvieras dependiendo de un paquete fantasma — agregalo a package.json y seguí adelante.

📖 Resumen en Telegram: Ver resumen

Preguntas frecuentes

¿pnpm es compatible con npm y yarn?

Sí. pnpm usa el mismo registro (npmjs.org) y el mismo formato de package.json. La diferencia está en el lockfile (pnpm-lock.yaml vs package-lock.json) y en la estructura física de node_modules. La mayoría de los proyectos se migran corriendo simplemente pnpm import para convertir el lockfile existente.

¿Puedo usar pnpm en producción y en Docker?

Sí, de hecho muchos proyectos grandes lo hacen. Para Docker, la recomendación es instalar pnpm con Corepack, copiar primero package.json y pnpm-lock.yaml, correr pnpm install --frozen-lockfile y después copiar el código fuente. Eso aprovecha el caché de layers de Docker al máximo.

¿Qué pasa si borro el almacén global?

Todos los proyectos que dependen de él muestran enlaces rotos y hay que correr pnpm install de nuevo en cada uno. No es una catástrofe, pero es un proceso que puede tardar. Podés limpiar partes viejas con pnpm store prune, que elimina solo paquetes ya no referenciados.

¿pnpm funciona con TypeScript, Next.js, Vite, etc.?

Sí, sin configuración extra. Todos los frameworks modernos del ecosistema JavaScript son compatibles. Vite, Next.js, Nuxt, SvelteKit, Remix y Astro tienen ejemplos oficiales con pnpm. TypeScript funciona exactamente igual.

¿Cuál es la diferencia con yarn berry (Plug’n’Play)?

Yarn PnP también elimina node_modules pero lo reemplaza con un archivo de resolución virtual. Esto es más agresivo y a veces incompatible con herramientas legacy. pnpm mantiene node_modules como carpeta real con symlinks, lo que lo hace más compatible en la práctica, aunque menos extremo en optimización.

¿Vale la pena migrar un proyecto grande desde npm?

Si el proyecto es un monorepo, casi siempre sí. Si es una app standalone pequeña, el beneficio es menor. En equipos grandes, el ahorro acumulado en CI y en espacio local justifica la migración con creces. Empezá con un proyecto piloto, medí los tiempos, y decidí con datos reales.

Referencias

• pnpm — Installation — documentación oficial sobre instalación en todas las plataformas.
• pnpm.io — sitio oficial del proyecto con documentación completa y changelogs.
• pnpm en GitHub — repositorio del código fuente y los issues del proyecto.
• Node.js — Corepack — documentación oficial del sistema de gestión de package managers incluido en Node.js.

📱 ¿Te gusta este contenido? Únete a nuestro canal de Telegram @programacion donde publicamos a diario lo más relevante de tecnología, IA y desarrollo. Resúmenes rápidos, contenido fresco todos los días.