Guía Completa de npm para Principiantes: Package Manager

# Guía Completa de npm para Principiantes: Package Manager

Si trabajas con JavaScript, verás npm constantemente. Esta guía explica qué es npm, cómo usarlo y comandos esenciales que todo desarrollador debe conocer.

---

¿Qué es npm?

npm (Node Package Manager) es el gestor de paquetes por defecto para Node.js.

Simplificado

npm = App Store para código JavaScript

En vez de descargar manualmente bibliotecas, npm lo hace por ti automáticamente.

¿Qué Hace npm?

✅ Instala paquetes/bibliotecas

✅ Gestiona versiones

✅ Maneja dependencias

✅ Ejecuta scripts

✅ Publica paquetes propios

---

Instalación de npm

npm Viene con Node.js

# Verificar si tienes Node.js
node --version
# v18.19.0

# Verificar npm
npm --version
# 10.2.3

¿No tienes Node.js?

Descarga en nodejs.org

Instala (incluye npm automáticamente)

Reinicia terminal

---

package.json: El Corazón de npm

Todo proyecto npm tiene un archivo package.json.

Crear package.json

npm init
# Responde preguntas interactivamente

# O usa configuración por defecto:
npm init -y

Ejemplo package.json

{
  "name": "mi-proyecto",
  "version": "1.0.0",
  "description": "Mi primer proyecto npm",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "test": "jest"
  },
  "dependencies": {
    "express": "^4.18.2"
  },
  "devDependencies": {
    "nodemon": "^3.0.1"
  }
}

Secciones Importantes

• name: Nombre del proyecto
• version: Versión actual
• scripts: Comandos personalizados
• dependencies: Paquetes para producción
• devDependencies: Paquetes solo desarrollo

---

Comandos npm Esenciales

1. Instalar Paquetes

Instalar paquete en producción

npm install express
# o la forma corta:
npm i express

Esto añade a dependencies:

"dependencies": {
  "express": "^4.18.2"
}

Instalar para desarrollo

npm install --save-dev nodemon
# Forma corta:
npm i -D nodemon

Instalar globalmente

npm install -g typescript

2. Instalar Todas las Dependencias

npm install
# O simplemente:
npm i

Lee package.json e instala todo lo listado.

3. Desinstalar Paquetes

npm uninstall express
# O:
npm un express

4. Actualizar Paquetes

# Ver paquetes desactualizados
npm outdated

# Actualizar todos
npm update

# Actualizar uno específico
npm update express

5. Ejecutar Scripts

// package.json
"scripts": {
  "start": "node index.js",
  "dev": "nodemon index.js",
  "test": "jest"
}

npm start
npm run dev
npm test

---

node_modules: La Carpeta Mágica

¿Qué es node_modules?

Carpeta donde npm guarda todos los paquetes instalados.

mi-proyecto/
├── node_modules/    ← Todos los paquetes aquí
│   ├── express/
│   ├── react/
│   └── ...miles de carpetas
├── package.json
└── index.js

⚠️ NUNCA subas node_modules a Git

Tamaño: Puede ocupar cientos de MB o GB. .gitignore:

node_modules/

¿Por qué?

• package.json ya lista las dependencias
• Otros pueden hacer npm install para obtenerlas

---

Versionado Semántico

Formato: MAJOR.MINOR.PATCH

"express": "4.18.2"
           │  │  │
           │  │  └─ PATCH - Bug fixes
           │  └──── MINOR - Nuevas features
           └─────── MAJOR - Breaking changes

Símbolos de Versión

| Símbolo | Significado | Ejemplo | Instala |

|---------|-------------|---------|---------|

| Exacto | Versión exacta | 4.18.2 | 4.18.2 |

| ^ | Compatible MINOR | ^4.18.2 | 4.x.x (menor a 5.0.0) |

| ~ | Compatible PATCH | ~4.18.2 | 4.18.x |

| | Cualquiera | | Última versión |

Ejemplo

"dependencies": {
  "express": "^4.18.2"  // Instala 4.18.2, 4.19.0, 4.20.1
                         // NO instala 5.0.0 (breaking)
}

---

package-lock.json

¿Qué es?

Archivo que bloquea versiones exactas de todas las dependencias y sub-dependencias.

Diferencia con package.json

| package.json | package-lock.json |

|--------------|-------------------|

| "express": "^4.18.2" | "express": "4.18.2" (exacto) |

| General | Exacto |

| Editas tú | Genera npm automáticamente |

¿Debes commitear package-lock.json?

✅ SÍ - Asegura que todos usen mismas versiones.

---

npx: Ejecutar sin Instalar

npx ejecuta paquetes sin instalarlos globalmente.

Crear App React

# Sin npx - instalación global necesaria
npm install -g create-react-app
create-react-app mi-app

# Con npx - sin instalación
npx create-react-app mi-app

Otros Usos de npx

# Crear app Vite
npx create-vite@latest

# Ejecutar TypeScript
npx ts-node script.ts

# Servidor local rápido
npx http-server

---

Scripts Personalizados

Scripts Comunes

{
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "build": "webpack",
    "test": "jest",
    "lint": "eslint ."
  }
}

Ejecutar Scripts

npm start      # Scripts especiales (no necesita 'run')
npm run dev    # Otros scripts necesitan 'run'
npm test       # Script especial
npm run build

Encadenar Comandos

{
  "scripts": {
    "clean": "rm -rf dist",
    "build": "webpack",
    "deploy": "npm run clean && npm run build"
  }
}

---

Buscar Paquetes

npmjs.com

🔍 npmjs.com

Busca por:

• Nombre: "react", "express"
• Funcionalidad: "http client", "css framework"

Información Importante

Antes de instalar, verifica:

✅ Descargas semanales - Popularidad

✅ Última actualización - ¿Mantenido?

✅ Issues en GitHub - ¿Muchos bugs?

✅ Tamaño del paquete - ¿Pesado?

✅ Licencia - ¿Puedes usarlo?

---

Comandos Útiles Adicionales

Ver Información de Paquete

npm info express
npm view express version

Listar Paquetes Instalados

# Locales (proyecto)
npm list

# Globales
npm list -g --depth=0

Auditar Seguridad

npm audit
npm audit fix  # Intenta arreglar automáticamente

Limpiar Caché

npm cache clean --force

---

Paquetes Populares

Desarrollo Web

| Paquete | Descripción | Instalación |

|---------|-------------|-------------|

| express | Framework web | npm i express |

| react | UI library | npm i react react-dom |

| vue | Framework progresivo | npm i vue |

| next | Framework React | npm i next |

Herramientas

| Paquete | Descripción | Instalación |

|---------|-------------|-------------|

| nodemon | Auto-reload dev | npm i -D nodemon |

| eslint | Linter JavaScript | npm i -D eslint |

| prettier | Formateador código | npm i -D prettier |

| jest | Testing framework | npm i -D jest |

Utilidades

| Paquete | Descripción | Instalación |

|---------|-------------|-------------|

| axios | HTTP client | npm i axios |

| lodash | Utilidades JS | npm i lodash |

| dayjs | Manejo de fechas | npm i dayjs |

| dotenv | Variables de entorno | npm i dotenv |

---

npm vs yarn vs pnpm

Alternativas a npm

| Característica | npm | yarn | pnpm |

|----------------|-----|------|------|

| Velocidad | Normal | Rápido | Muy rápido |

| Espacio disco | Normal | Normal | Mínimo |

| Lockfile | package-lock.json | yarn.lock | pnpm-lock.yaml |

| Popularidad | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |

Comandos Equivalentes

| npm | yarn | pnpm |

|-----|------|------|

| npm install | yarn | pnpm install |

| npm i express | yarn add express | pnpm add express |

| npm un express | yarn remove express | pnpm remove express |

---

Solución de Problemas

Error: EACCES (Permisos)

❌ NO hagas esto:

sudo npm install  # ❌ Peligroso

✅ Solución:

# Cambiar permisos de directorio npm
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Error: Cannot find module

Solución:

rm -rf node_modules package-lock.json
npm install

Versión incompatible

package.json:

{
  "engines": {
    "node": ">=18.0.0",
    "npm": ">=9.0.0"
  }
}

---

Publicar Tu Propio Paquete

Pasos Básicos

1. Crear cuenta en npmjs.com 2. Login desde terminal

npm login

3. Preparar package.json

{
  "name": "mi-paquete-unico",  // Debe ser único
  "version": "1.0.0",
  "main": "index.js"
}

4. Publicar

npm publish

---

Mejores Prácticas

✅ DO's

Usa package-lock.json - Commitea siempre

Especifica versiones de Node en engines

Audita seguridad regularmente

Mantén dependencias actualizadas

Usa .npmrc para configuración

❌ DON'Ts

No instales todo globalmente

No ignores warnings de seguridad

No subas node_modules a Git

No uses paquetes abandonados

---

Conclusión

npm es esencial para desarrollo JavaScript moderno:

✅ Gestiona dependencias fácilmente

✅ Miles de paquetes disponibles

✅ Scripts personalizados

✅ Seguridad con audit

✅ Comunidad enorme

Próximo paso: Crea un proyecto, instala paquetes y experimenta con scripts npm.

---

Recursos Relacionados

• JavaScript y JSON
• ¿Qué es React?
• Crear API REST

---

Última actualización: 15 de febrero de 2026