Comandos de npm: guía de gestión de paquetes

01Qué es npm y para qué sirve

npm (Node Package Manager) es el gestor de paquetes del mundo JavaScript. Permite añadir a su proyecto bibliotecas escritas por otros, seguir sus versiones y ejecutar desde un solo lugar los comandos relacionados con el proyecto.

npm viene incluido con Node.js; no hace falta instalarlo aparte. Si aún no ha instalado Node.js, siga primero nuestra guía de instalación de Node.js y después pruebe los comandos de este artículo en su propio terminal.

npm tiene tres partes: la herramienta de línea de comandos de su equipo, el registro (registry) donde se alojan los paquetes y el archivo package.json, que es el corazón de cada proyecto. Casi todos los comandos leen o actualizan este archivo.

02Qué es package.json

package.json es el documento de identidad del proyecto: aquí figuran su nombre, su versión, sus dependencias y los scripts que se pueden ejecutar. En un proyecto nuevo se crea este archivo con npm init; la opción -y salta todas las preguntas con la respuesta predeterminada.

• dependencies: los paquetes que la aplicación necesita mientras funciona.
• devDependencies: las herramientas necesarias solo durante el desarrollo y la compilación (compilador, herramienta de pruebas, formateador).
• scripts: comandos cortos que se ejecutan con npm run.
• package-lock.json: registra la versión exacta de cada paquete instalado; añada siempre este archivo a Git.

mkdir ilk-proje
cd ilk-proje
npm init -y

{
  "name": "ilk-proje",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "node --test"
  },
  "dependencies": {
    "axios": "^1.7.0"
  },
  "devDependencies": {
    "vite": "^6.0.0"
  }
}

03Instalar paquetes con npm install

npm install es el comando más utilizado y hace dos trabajos distintos. Escrito solo, instala en la carpeta node_modules todas las dependencias de package.json; escrito con el nombre de un paquete, instala ese paquete y lo añade a package.json. Su forma abreviada es npm i.

# Instalar todas las dependencias del proyecto
npm install

# Yeni paket ekle (dependencies)
npm install axios

# Añadir una herramienta de desarrollo (devDependencies)
npm install -D prettier

# Instalar una versión concreta
npm install lodash@4

# Instalación global (para herramientas de línea de comandos)
npm install -g serve

# Desinstalar el paquete
npm uninstall axios

¿Global o local?

Instale los paquetes de forma local siempre que pueda; así el proyecto funciona con la misma versión en otro equipo. Reserve la instalación global para las herramientas de línea de comandos que usará en todas partes; para las herramientas de un solo uso, npx es suficiente.

¿Cuándo se usa npm ci?

npm ci borra la carpeta node_modules e instala exactamente las versiones de package-lock.json, sin modificar el archivo de bloqueo. Es ideal para el despliegue en el servidor, para las líneas de integración continua y para resolver los problemas del tipo «en mi equipo funcionaba».

04Ejecutar scripts con npm run

El campo scripts de package.json permite dar nombres cortos a comandos largos. Así, todos los miembros del equipo inician el servidor de desarrollo con npm run dev y la compilación de producción con npm run build sin conocer los detalles de la herramienta.

Algunos nombres, como start y test, son especiales y funcionan sin escribir run. Para pasar parámetros adicionales al script se usan dos guiones.

npm run dev
npm run build
npm start
npm test

# Listar todos los scripts definidos
npm run

# Pasar parámetros al script
npm run build -- --mode staging

Scripts pre y post

Si añade pre o post al principio del nombre de un script, npm lo ejecuta automáticamente antes o después. Por ejemplo, un script llamado prebuild puede limpiar la carpeta de compilación anterior justo antes de npm run build. Este esquema garantiza que nadie del equipo olvide un paso.

Por qué los scripts encuentran las herramientas locales

Mientras se ejecuta, npm run añade temporalmente al PATH la carpeta node_modules/.bin del proyecto. Por eso en el script basta con escribir vite o prettier; no hace falta instalar la herramienta de forma global. Si la misma herramienta no se encuentra al escribirla directamente en el terminal, el motivo es este, y la solución es usar npx.

Diferencias de sistema operativo en los scripts

Comandos como rm -rf no funcionan en el shell predeterminado de Windows. Si en el equipo hay sistemas operativos distintos, prefiera en los scripts herramientas de Node.js independientes de la plataforma o pequeños scripts de Node.js; así el mismo package.json da el mismo resultado en todas las máquinas.

05Actualizar y auditar paquetes

Los paquetes se actualizan con regularidad: se corrigen vulnerabilidades y llegan funciones nuevas. Antes de actualizar, ejecute el comando npm outdated para ver qué se ha quedado antiguo.

El signo ^ en package.json permite versiones menores y de parche (1.7.0 → 1.9.2), y el signo ~ solo versiones de parche (1.7.0 → 1.7.5). npm update actualiza dentro de esos límites; para saltar de versión principal hay que reinstalar el paquete con @latest, y esto suele exigir cambios en el código.

# Eskiyen paketleri listele
npm outdated

# Actualizar dentro del rango permitido
npm update

# Pasar a la versión principal (úselo con cuidado)
npm install axios@latest

# Auditoría de seguridad
npm audit
npm audit fix

# Ver los paquetes instalados
npm ls --depth=0
npm ls -g --depth=0

# Última versión publicada de un paquete
npm view axios version

06Qué es npx y cuándo usarlo

npx es un ejecutor de paquetes que viene con npm. Permite ejecutar una herramienta una sola vez, sin instalarla de forma global; primero se busca la herramienta en node_modules del proyecto y, si no está, se descarga temporalmente.

Crear una plantilla de proyecto es el uso más habitual de npx. Por ejemplo, para abrir un proyecto React nuevo con Vite se usa el comando npm create; encontrará los detalles en nuestro artículo de instalación de React con Vite.

# Servir la carpeta en un servidor local
npx serve .

# Ejecutar el formateador instalado en el proyecto
npx prettier --write .

# Nuevo proyecto a partir de una plantilla (hace lo mismo que npm create, npx create-...)
npm create vite@latest

07Diferencias entre npm, yarn y pnpm

npm no es la única opción; yarn y pnpm también instalan paquetes desde el mismo registro. Como los tres usan package.json, la estructura del proyecto no cambia; la diferencia aparece en la velocidad de instalación, el uso de disco y el archivo de bloqueo.

• Use un único gestor de paquetes por proyecto; tener dos archivos de bloqueo a la vez provoca confusión de versiones.
• Si se incorpora a un proyecto existente, mire el archivo de bloqueo de la carpeta y elija la misma herramienta.
• Si está empezando, comenzar con npm es el camino con menos fricción.

08Errores frecuentes y soluciones

La mayoría de los errores de npm se deben a una caché dañada, a una versión de Node.js incompatible o a dependencias en conflicto. Lea primero las primeras líneas del mensaje de error; la solución suele explicarse ahí.

• Error ERESOLVE / peer dependency: uno de los paquetes espera una versión distinta de otro paquete. Actualice los paquetes a versiones compatibles; como solución provisional puede usarse npm install --legacy-peer-deps.
• node_modules dañado: borre la carpeta node_modules y ejecute npm install o npm ci. Borrar el archivo de bloqueo es el último recurso.
• Problema de caché: npm cache verify comprueba la caché; si hace falta, límpiela con npm cache clean --force.
• Error de permisos EACCES: no use sudo en la instalación global; reinstale Node.js con nvm.
• Aviso de engine: si el paquete pide un Node.js más reciente, pase a la versión LTS con nvm.

09Usar bien npm en los proyectos

Tener más paquetes de los necesarios aumenta tanto el riesgo de seguridad como la cantidad de JavaScript que la página envía al navegador. Preguntarse antes de cada nueva dependencia «¿puedo resolver esto con unas pocas líneas de código?» es la optimización más barata para la velocidad de la página. Tratamos este tema con regularidad en nuestro servicio de velocidad y rendimiento.

No añada nunca la carpeta node_modules a Git; inclúyala en el archivo .gitignore y comparta solo package.json y el archivo de bloqueo. Explicamos paso a paso cómo enviar el proyecto al repositorio remoto en nuestra guía de subir un proyecto a GitHub.

Si planea para su negocio un proyecto de diseño web o de integración que conecte los sistemas de pago, envíos y contabilidad, plantear bien desde el principio la gestión de dependencias reduce a largo plazo el coste de mantenimiento. Para más contenidos sobre Node.js, consulte la página de la etiqueta nodejs.