Tema 4 · package.json & SemVer

4. Anatomía de package.json, SemVer (^ y ~) y el Rol de package-lock.json

Desglosa el archivo manifiesto de Node: campos clave, versionado semántico SemVer (Caret vs Tilde) y por qué package-lock.json garantiza builds deterministas.

El Manifiesto del Proyecto: package.json

Todo proyecto profesional en el ecosistema de Node.js gira alrededor de un archivo central: package.json. Este documento en formato JSON actúa como la cédula de identidad del software, definiendo metadatos, paquetes externos necesarios y comandos automatizados.

Para inicializar un proyecto nuevo con valores predeterminados seguros en un solo segundo:

npm init -y
Ecosistema npm package.json y package-lock.json

Diagrama 2: Relación arquitectónica entre package.json, las reglas SemVer, el candado de integridad y node_modules.

Campos Esenciales de package.json

  • name: Nombre único del paquete (en minúsculas, sin espacios ni caracteres especiales).
  • version: Versión actual del software siguiendo la convención SemVer.
  • private: true: Evita accidentes impidiendo que el código de una aplicación privada sea publicado por error en el registro público de npm.
  • type: Declara "module" para ES Modules o "commonjs".
  • scripts: Atajos ejecutables como npm start, npm test o npm run build.
  • engines: Especifica el rango de versiones de Node compatibles (ej. { "node": ">=20.0.0" }).

El Sistema SemVer (Semantic Versioning)

Las versiones en el registro de npm siguen el estándar MAJOR.MINOR.PATCH (ejemplo: 4.19.2):

MAJOR (4.0.0)

Cambios incompatibles que rompen código anterior (Breaking Changes).

MINOR (4.19.0)

Nuevas funcionalidades que mantienen compatibilidad hacia atrás.

PATCH (4.19.2)

Correcciones de errores, fallos de seguridad y parches ligeros.

Los símbolos que acompañan a la versión en dependencies determinan la flexibilidad al ejecutar npm update:

  • Caret ^4.19.2 (Por defecto): Acepta parches y mejoras menores sin romper el proyecto (cualquier versión >= 4.19.2 y < 5.0.0).
  • Tilde ~4.19.2: Solo acepta parches de corrección (cualquier versión >= 4.19.2 y < 4.20.0).
  • Exacta 4.19.2: Bloquea la versión estrictamente a ese valor.

¿Por qué package-lock.json es Sagrado en Producción?

El archivo package.json solo define rangos de versiones deseadas. Si un desarrollador instala hoy y otro instala dentro de 6 meses, podrían obtener subversiones diferentes que introduzcan errores inadvertidos.

package-lock.json resuelve esto: guarda el árbol exacto de todas las subdependencias, la URL de descarga y el hash criptográfico (integrity sha512).

💡 Comando Recomendado en Servidores VPS:
En producción y flujos CI/CD de GitHub Actions, siempre ejecuta npm ci --omit=dev en lugar de npm install. El comando ci (Clean Install) es mucho más veloz y garantiza que nada altere el lockfile.

⚡ Estructura Completa de un package.json Profesional para Producción

Configuración estándar recomendada con metadatos, scripts de ciclo de vida y dependencias fijadas:

package.json
Solo lectura
{
  "name": "kilopolis-backend-api",
  "version": "1.2.0",
  "description": "API REST de alto rendimiento para Kilopolis Academia en Servidores VPS",
  "private": true,
  "type": "module",
  "main": "src/server.js",
  "scripts": {
    "dev": "node --watch src/server.js",
    "start": "node src/server.js",
    "test": "node --test",
    "lint": "eslint src/"
  },
  "dependencies": {
    "cors": "^2.8.5",
    "dotenv": "^16.4.5",
    "express": "^4.19.2",
    "jsonwebtoken": "^9.0.2"
  },
  "devDependencies": {
    "eslint": "^9.3.0"
  },
  "engines": {
    "node": ">=20.0.0",
    "npm": ">=10.0.0"
  },
  "license": "MIT"
}
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
En el archivo package.json, ¿qué significa que una dependencia esté registrada como "^4.18.2"?
🦉
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.

🚀 ¿Quieres dominar Node.js & npm Profesional y crear proyectos reales?

Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.

🏛️ Autoría y Propiedad Intelectual: Obra educativa original de Juan Sebastián Amador para Kilopolis Academia, estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.