pnpm vs npm: almacenamiento, lockfiles, workspaces y comandos | We.Inc
Cómo guardan los paquetes pnpm y npm, cómo fijan versiones y gestionan monorepos, un traductor con buscador de comandos de npm a pnpm y los pasos exactos para migrar un proyecto con seguridad.
npm copia cada paquete en el node_modules de cada proyecto y los eleva todos a un nivel plano. pnpm mantiene en disco un único almacén direccionable por contenido, crea hard links desde él y solo pone tus dependencias directas en la raíz de node_modules. Eso ahorra espacio en disco e impide que el código importe paquetes que nunca declaró. La mayoría de los comandos tienen equivalencia directa.
Diferencias clave
Tema
Dónde viven los archivos de los paquetes
Una copia dentro de cada proyecto
Un almacén compartido, enlazado con hard links en los proyectos
Estructura de node_modules
Plana, todo elevado
Solo dependencias directas, el resto en node_modules/.pnpm
Lockfile
Workspaces declarados en
Instalación estricta en CI
npm ci
pnpm install (frozen lockfile es el valor por defecto en CI)
Ejecutar un paquete sin instalarlo
pnpm dlx (también pnx, pnpx)
Las dos herramientas leen el mismo package.json e instalan desde el mismo registro, así que la elección depende de la estructura, la velocidad de las instalaciones repetidas, las herramientas para monorepos y el nivel de rigor. Abajo verás cómo guarda los paquetes cada una, un traductor para los comandos que ya conoces y los pasos para pasar un proyecto existente de npm a pnpm.
Escribe un comando de npm en el traductor, o haz clic en uno de los ejemplos, para ver su equivalente en pnpm.
Lee la sección de almacenamiento para entender por qué las instalaciones de pnpm ocupan menos disco y detectan imports no declarados.
Sigue los pasos de migración si decides cambiar, y haz commit del nuevo lockfile.
Elige un único gestor de paquetes por repositorio y borra el otro lockfile, para que nadie instale desde uno desactualizado.
En CI, pnpm install se niega a modificar un lockfile desactualizado, así que haz commit de pnpm-lock.yaml cada vez que cambie package.json.
Si un paquete falla con pnpm porque importa algo que nunca declaró, repórtalo a sus autores; ese import solo funcionaba por casualidad con npm.
pnpm ejecuta scripts sin la palabra run, así que pnpm dev funciona, siempre que el nombre del script no choque con un comando integrado de pnpm.
Preguntas frecuentes
¿Es pnpm más rápido que npm?
pnpm a menudo reutiliza archivos que ya están en su almacén, lo que ayuda en instalaciones repetidas en la misma máquina. La velocidad depende del estado de la caché, la red y el tamaño del proyecto, así que mide los dos en tu propio proyecto en lugar de fiarte de un benchmark publicado.
¿Puedo usar pnpm en un proyecto que tiene package-lock.json?
Sí. Ejecuta pnpm import para generar un pnpm-lock.yaml a partir de package-lock.json, npm-shrinkwrap.json o yarn.lock, luego borra el lockfile antiguo y node_modules y ejecuta pnpm install.
¿Por qué mi app no encuentra un módulo después de cambiar a pnpm?
Tu código, o una dependencia, importa un paquete que no figura en su propio package.json. La estructura plana de npm ocultaba ese error. Añade el paquete que falta como dependencia de lo que lo importa.
¿Necesita pnpm tener Node.js instalado?
La documentación de instalación de pnpm describe pnpm 12 como un ejecutable nativo que no necesita Node.js para funcionar. Los scripts de tu proyecto, por supuesto, siguen necesitando Node.js.
¿Cuál debería usar alguien que empieza?
npm, porque viene con Node.js y casi todos los tutoriales lo usan. Pasa a pnpm cuando tengas un monorepo, muchos proyectos en una misma máquina, o quieras la estructura de node_modules más estricta.
Cómo guarda los paquetes cada herramienta
npm escribe una copia completa de cada dependencia en el node_modules del proyecto y sube las dependencias anidadas al nivel superior siempre que puede. Diez proyectos que usan la misma librería guardan diez copias.
pnpm descarga cada archivo una sola vez en un almacén global direccionable por contenido. Los proyectos reciben hard links a esos archivos, así que un segundo proyecto con las mismas versiones apenas ocupa espacio extra, y una versión nueva solo añade los archivos que cambiaron.
Dentro del proyecto, pnpm coloca symlinks para tus dependencias directas en node_modules y guarda todo lo demás en node_modules/.pnpm. Un paquete solo puede acceder a lo que declaró.
Workspaces y monorepos
Los workspaces de npm se enumeran en el package.json raíz y se ejecutan con -w nombre o --workspaces. pnpm los enumera en pnpm-workspace.yaml y los selecciona con --filter, que además entiende grafos de dependencias, por ejemplo un paquete más todo aquello de lo que depende.
El protocolo workspace: de pnpm fija una dependencia al paquete local y se niega a recurrir al registro. Se convierte en un rango de versiones normal cuando publicas.
Pasar un proyecto de npm a pnpm
Pasos de migración
pnpm import lee el lockfile de npm para que conserves las versiones que ya probaste. Ejecuta tus tests antes de hacer commit.
Cada carpeta que coincida aquí se convierte en un paquete del workspace. Pon el archivo en la raíz del repositorio.
Depender de un paquete local
workspace:* siempre se resuelve a la copia local de ui en lugar de a una versión del registro.
Traductor de comandos de npm a pnpm
Escribe un comando de npm
npm install -D vite
Equivalente en pnpm
No hay equivalencia directa. La mayoría de los demás comandos de npm tienen el mismo nombre en pnpm.