1.4npm: package.json, dependencias, scripts, versiones
Lo esencial en 30 segundos
- package.json = el manifiesto: nombre, versión, dependencias, scripts — creado con npm init, punto de referencia de todo proyecto.
- La receta, no el resultado: se versionan package.json + package-lock.json (versiones exactas), nunca node_modules (regenerable vía npm install).
- Semver + scripts + auditoría: MAYOR.MENOR.PARCHE (^ y ~), comandos estándar vía npm run, vulnerabilidades vía npm audit.
Minicaso hilado — Salim inicializa su proyecto en Argel
Salim recupera el proyecto de la startup: una carpeta con código pero sin package.json, y un compañero le envía node_modules como adjunto. Empieza de forma limpia: npm init para crear el manifiesto, instalación de los paquetes (dependencias frente a devDependencies), scripts start/dev/test, .gitignore que excluye node_modules, y un primer npm audit que revela una dependencia vulnerable que actualizar. El proyecto se vuelve instalable con un comando: npm install.
Último episodio del caso 1.1-1.3 — Salim equipa su proyecto tras el lenguaje, la asincronía y los módulos.
1. package.json y dependencias: el manifiesto
npm da acceso al mayor registro open source del mundo: se instalan paquetes en lugar de codificarlo todo. El corazón del proyecto es package.json (nombre, versión, dependencias, scripts), creado con npm init. npm install express descarga en node_modules y añade a las dependencias. Se distinguen dependencies (producción) y devDependencies (solo dev, -D). El package-lock.json fija las versiones exactas (reproducibilidad); node_modules no se versiona (regenerable).
Salim lanza npm init -y, instala el framework como dependencia y la herramienta de reinicio como devDependency: el proyecto ya se instala con un npm install en cualquier equipo.
2. Semver, scripts y seguridad
El versionado semántico (semver) sigue MAYOR.MENOR.PARCHE: mayor = cambios incompatibles, menor = novedades compatibles, parche = errores. ^4.18.2 autoriza actualizaciones menores/de parche, ~4.18.2 solo de parche. Los scripts (start, dev, test) se lanzan con npm run <nom> y estandarizan los comandos. Y npm audit señala las vulnerabilidades de las dependencias — a vigilar, pues los fallos de dependencias son un riesgo real.
Salim define start, dev y test en sus scripts y hace de npm audit su reflejo antes de cada puesta en producción.
3. Elegir sus paquetes sin exponerse
El ecosistema inmenso es una fuerza (no reinventar la rueda) y un riesgo (fallos, calidad variable, paquetes abandonados). Para elegir: popularidad (descargas, adopción), mantenimiento activo (actualizaciones recientes, issues tratados), documentación seria, perímetro mínimo (no un gran paquete para una función trivial). Y en Git: se versionan package.json + lock, nunca node_modules ni los secretos (.env).
Salim verifica las descargas y la última actualización antes de instalar, y añade node_modules/ y .env al .gitignore desde el primer commit.
🔎 Ejemplo concreto — 🔎 Ejemplo concreto — Inicializar e instalar
Los comandos básicos, en orden.
npm init -y # crea package.json
npm install express # dependencia (producción)
npm install -D nodemon # devDependency (dev)
npm run dev # ejecuta el script "dev"
npm audit # vulnerabilidades conocidasLectura: -D marca las herramientas de dev; npm run lanza los scripts del manifiesto.
Lección: ignorar node_modules y .env en .gitignore — reflejo desde el primer commit.
Vocabulario de la sección
- npm y el registro
- Gestor de paquetes de Node, que da acceso al mayor registro open source del mundo (cientos de miles de bibliotecas reutilizables).
Ejemplo sencillo: El framework web instalado por Salim en lugar de recodificarlo.
Lo que no es: recodificar uno mismo un router HTTP o un cliente de base.
Reflejo: buscar el paquete probado antes de recodificar.
- package.json
- Manifiesto del proyecto: nombre, versión, dependencias, scripts, metadatos. Creado con npm init; punto de referencia de todo proyecto Node.
Ejemplo sencillo: El package.json de Salim con start, dev y test.
Lo que no es: una carpeta de código sin manifiesto, no instalable limpiamente.
Reflejo: npm init desde el primer día del proyecto.
- dependencies frente a devDependencies
- dependencies: necesarias en producción. devDependencies: útiles solo en dev (instaladas con -D). node_modules: carpeta de los paquetes instalados, no versionada, regenerable.
Ejemplo sencillo: El framework en dependencies, la herramienta de reinicio en devDependencies en casa de Salim.
Lo que no es: enviar node_modules como adjunto al compañero.
Reflejo: -D para las herramientas, Git ignora node_modules.
- package-lock.json
- Archivo que fija las versiones EXACTAS instaladas; garantiza que todo el mundo instale rigurosamente las mismas versiones (reproducibilidad).
Ejemplo sencillo: El lock que hace que el equipo de Salim y la producción instalen lo mismo.
Lo que no es: «en mi equipo funciona» con versiones distintas en todas partes.
Reflejo: versionar el lock, nunca editarlo a mano.
- semver y scripts npm
- Versionado MAYOR.MENOR.PARCHE (^ autoriza menores/parche, ~ solo parche). Los scripts definen comandos reutilizables (npm run
). Ejemplo sencillo: El ^ que deja pasar los parches de seguridad en casa de Salim, y su npm run dev.
Lo que no es: versiones congeladas para siempre o comandos distintos por desarrollador.
Reflejo: entender ^ / ~, estandarizar vía los scripts.
En la práctica — En la práctica — Gestionar un proyecto con npm
- Inicialice un proyecto con npm init -y y examine el package.json generado (nombre, versión, scripts).
- Instale un paquete (npm install express) y una devDependency (npm install -D nodemon); observe node_modules, package.json y package-lock.json.
- Añada scripts al package.json ("start", "dev") y láncelos con npm start / npm run dev.
- Entienda el semver (^ frente a ~), ignore node_modules (.gitignore) y lance npm audit para detectar vulnerabilidades.
Guion listo para decir — pautar la higiene npm en equipo (30 s)
«Versionamos package.json y el lock, nunca node_modules — cada uno regenera con npm install. Las herramientas de dev van en -D, los comandos en scripts, y hacemos un npm audit antes de cada entrega.»
Para decir al arrancar el proyecto; verificar el .gitignore en el primer commit.
Modelo copiar-pegar — package.json mínimo + .gitignore
{
"name": "projet-salim",
"version": "1.0.0",
"scripts": {
"start": "node app.js",
"dev": "nodemon app.js",
"test": "jest"
},
"dependencies": {},
"devDependencies": {}
}
// .gitignore :
// node_modules/
// .envProyecto sin manifiesto
Como Salim: npm init -y, reinstalar los paquetes uno por uno distinguiendo prod y -D, recrear los scripts — nunca recuperar un node_modules ajeno.
Equipo en Argel
Scripts start/dev/test idénticos para todos: cada desarrollador lanza los mismos comandos, se acabó el «yo lo hacía de otra forma».
Subida de versión prudente
Leer lo que ^ y ~ autorizan antes de actualizar; probar tras cada subida menor, fijar vía el lock.
Entrega inminente
npm audit antes de entregar: corregir las vulnerabilidades señaladas, verificar que .env y node_modules quedan fuera de Git.
✓ Buenas prácticas
- Versionar json + lock, nunca node_modules.
- Herramientas de dev en -D, comandos en scripts.
- npm audit antes de cada entrega.
✗ Errores frecuentes
- Versionar node_modules.
- Olvidar .env en .gitignore.
- Ignorar las alertas npm audit.
Puntos clave
- npm da acceso al mayor registro open source del mundo: instalar paquetes en lugar de codificarlo todo — acelerador clave.
- package.json = manifiesto (dependencias, scripts); package-lock.json fija las versiones EXACTAS. node_modules NO versionado (regenerable).
- dependencies (producción) frente a devDependencies (dev, -D); SEMVER MAYOR.MENOR.PARCHE (^ menores/parche, ~ parche).
- SCRIPTS npm estandarizan los comandos; npm audit señala las vulnerabilidades (a vigilar).
Reto 48h — aplíquelo mañana
Inicialice un proyecto real (modelo anterior): npm init -y, 1 paquete + 1 devDependency (-D), 2 scripts, .gitignore (node_modules, .env) y luego npm audit. 25 minutos bastan.
- Puedo explicar package.json, lock y node_modules.
- Sé distinguir dependencies, devDependencies y semver ^ / ~.
- Tengo un proyecto instalable vía npm install + auditado.
Preguntas frecuentes
¿Qué hay que versionar (Git) en un proyecto Node, y por qué no node_modules?
Versione su código, package.json (la «receta»: dependencias, scripts) y package-lock.json (las versiones exactas, incluidas las subdependencias) — más el .gitignore, el README y las configs. No versione nunca node_modules: es enorme (miles de archivos), regenerable con npm install desde ambos manifiestos, y a veces específico de la plataforma. Como Salim: se comparte la receta (json + lock), cada uno regenera el resultado. Excluya también los secretos (.env), logs y temporales.
El ecosistema npm es inmenso: ¿cómo elegir buenos paquetes?
No reinventar la rueda es una gran baza — pero las dependencias también son un riesgo (fallos, calidad variable, abandono). Para elegir: popularidad (descargas, estrellas — una buena señal), mantenimiento activo (actualizaciones recientes, issues tratados), documentación seria, perímetro mínimo (no un gran paquete para una nimiedad). Luego gestione: mantenga las dependencias al día (semver entendido), vigile npm audit y prefiera pocas dependencias probadas a una miríada de desconocidas.
¿Qué hay que versionar en Git para un proyecto Node?