¿Qué es npm y cómo administrar paquetes en tu proyecto?

npm es el gestor de paquetes oficial de Node.js que te permite instalar, actualizar y eliminar librerías de terceros en tu proyecto con un solo comando.

Cuando escribir código desde cero no tiene sentido

Imagina que trabajas en el equipo de tecnología de Liverpool. Te piden que el sistema calcule fechas de entrega considerando días hábiles, zonas horarias y festivos mexicanos. Podrías escribir esa lógica tú mismo. Tomaría semanas. O podrías instalar una librería que ya lo hace en segundos. Esa es la promesa de npm: no reinventar la rueda.

npm viene instalado automáticamente cuando instalas Node.js. Puedes verificarlo en tu terminal:

npm --version

Si ves un número como 9.8.1, estás listo para continuar.

El Sistema de Tres Capas de npm

Para entender npm de forma clara, piensa en él como un sistema de tres capas. Cada capa tiene una responsabilidad distinta.

Capa 1 — El registro público: Es la base de datos en línea donde viven más de dos millones de paquetes. Cualquier desarrollador en el mundo puede publicar un paquete ahí. Tú los descargas desde ese registro.

Capa 2 — El archivo package.json: Es el corazón de tu proyecto. Registra qué paquetes usas, qué versión de Node.js requieres y qué scripts puedes correr. Sin este archivo, tu proyecto no tiene memoria.

Capa 3 — La carpeta node_modules: Es donde npm guarda físicamente los paquetes que instalas. Esta carpeta puede pesar cientos de megabytes. Nunca la subas a Git.

Este sistema de tres capas te permite compartir tu proyecto con cualquier colega. Solo compartes el package.json, no la carpeta gigante. Tu colega corre npm install y reconstruye todo en segundos.

Cómo crear tu archivo package.json

Antes de instalar cualquier paquete, inicializa tu proyecto. Abre tu terminal en la carpeta de tu proyecto y corre:

npm init -y

El flag -y acepta todos los valores predeterminados automáticamente. Esto crea un archivo package.json como este:

{
  "name": "mi-proyecto",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Este archivo empieza vacío, pero crecerá cada vez que instales un paquete.

Instalar tu primer paquete: el caso de FEMSA

Supón que desarrollas una API para FEMSA que procesa reportes de ventas. Los números de cada tienda llegan como texto y necesitas formatearlos como moneda mexicana. El paquete numeral hace eso perfectamente.

Instálalo así:

npm install numeral

Después de correr ese comando, pasan tres cosas automáticamente:

1. npm descarga el paquete a node_modules.
2. Agrega numeral a la sección dependencies en tu package.json.
3. Crea o actualiza el archivo package-lock.json con la versión exacta instalada.

Tu package.json ahora se ve así:

{
  "dependencies": {
    "numeral": "^2.0.6"
  }
}

Ahora úsalo en tu código:

const numeral = require('numeral');

const ventasDiarias = 18500;
const formato = numeral(ventasDiarias).format('$0,0');

console.log('Ventas del día:', formato);
// Salida: Ventas del día: $18,500

Fíjate que en el require no usas ./. Recuerdas la lección anterior: sin ./, Node.js busca en node_modules. Aquí eso es exactamente lo que queremos.

Dependencias de desarrollo vs. dependencias de producción

No todos los paquetes son iguales. Algunos los necesitas solo cuando estás programando. Otros los necesitas cuando tu aplicación corre en el servidor de producción de Bimbo. npm distingue entre los dos.

Dependencias de producción (dependencies): Las instala tu servidor real. Ejemplo: una librería para conectarse a la base de datos.

npm install express

Dependencias de desarrollo (devDependencies): Solo las usas tú mientras programas. Ejemplo: herramientas para hacer pruebas o para recargar el servidor automáticamente.

npm install nodemon --save-dev

El flag --save-dev le dice a npm que este paquete va en devDependencies. Tu package.json queda así:

{
  "dependencies": {
    "express": "^4.18.2",
    "numeral": "^2.0.6"
  },
  "devDependencies": {
    "nodemon": "^3.0.1"
  }
}

Esta separación importa en producción. Cuando el servidor de Mercado Libre despliega tu app, puede instalar solo las dependencias necesarias con npm install --production. Eso hace el servidor más ligero y seguro.

Scripts: automatiza tu flujo de trabajo

La sección scripts del package.json es una de las más útiles y menos aprovechadas. Te permite definir comandos cortos para tareas repetitivas.

Supón que siempre arrancas tu servidor con node index.js. Puedes crear un atajo:

{
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "lint": "eslint ."
  }
}

Ahora en lugar de escribir el comando largo, escribes:

npm run dev

npm lee el script dev y ejecuta nodemon index.js. El script start es especial: puedes correrlo con npm start sin necesitar run.

Esto es útil cuando trabajas en equipo. Cualquier persona que entre al proyecto ve los scripts disponibles y sabe exactamente cómo arrancar, probar o construir el sistema.

Actualizar y eliminar paquetes

Los proyectos cambian. A veces necesitas una versión más nueva de un paquete. A veces ya no necesitas una librería.

Para actualizar un paquete:

npm update numeral

Esto instala la versión más nueva compatible con el rango definido en tu package.json.

Para ver qué paquetes tienen versiones nuevas disponibles:

npm outdated

Verás una tabla con el nombre del paquete, la versión actual, la versión que quieres y la versión más nueva disponible.

Para eliminar un paquete que ya no usas:

npm uninstall numeral

Esto borra el paquete de node_modules y lo elimina del package.json. Tu proyecto queda limpio.

Errores comunes al usar npm

Error 1 — Subir node_modules a Git: Esta carpeta puede tener miles de archivos y pesar más de $500 MB. Nunca la incluyas en tu repositorio. Crea un archivo .gitignore en la raíz de tu proyecto con esta línea:

node_modules/

Cualquier persona que clone tu repo corre npm install y reconstruye la carpeta en su máquina.

Error 2 — Ignorar el package-lock.json: Este archivo guarda las versiones exactas de cada paquete instalado. Si lo ignoras o borras, dos desarrolladores en el mismo equipo pueden tener versiones diferentes del mismo paquete. Eso causa bugs difíciles de rastrear. Siempre súbelo a Git.

Error 3 — Instalar paquetes globalmente para todo: El comando npm install -g nombre instala el paquete en tu máquina entera, no en el proyecto. Esto parece conveniente, pero crea problemas cuando el proyecto se mueve a otro servidor. Prefiere instalaciones locales siempre que sea posible.

Error 4 — No revisar qué instalas: Antes de instalar cualquier paquete, búscalo en npmjs.com. Revisa cuántas descargas semanales tiene y cuándo fue la última actualización. Un paquete con millones de descargas y mantenimiento activo es más confiable que uno abandonado hace tres años.

Cómo reconstruir un proyecto desde cero

Este flujo ocurre todo el tiempo. Tu colega del equipo de Bimbo te comparte el proyecto por Git. Recibes todo el código, pero no node_modules. Para que el proyecto funcione:

npm install

npm lee el package.json, descarga todos los paquetes listados en dependencies y devDependencies, y reconstruye node_modules completamente. Un solo comando. Todo listo.

Esta es la magia del sistema: el package.json actúa como receta. node_modules es el resultado. Siempre puedes regenerar el resultado a partir de la receta.

El hábito que separa a los principiantes de los profesionales

Los desarrolladores que mantienen proyectos saludables revisan sus dependencias regularmente. Corren npm outdated cada mes. Eliminan paquetes que ya no usan. Leen los changelogs antes de actualizar dependencias críticas.

Un proyecto de backend para una empresa como FEMSA o Liverpool puede vivir años en producción. Las dependencias desactualizadas acumulan vulnerabilidades de seguridad. El SAT no acepta "mi librería estaba vieja" como excusa cuando hay una fuga de datos.

npm no es solo una herramienta para instalar cosas: es el sistema que mantiene vivo y organizado tu proyecto a lo largo del tiempo.