NPM

Package.json en profundidad: la Ficha técnica de tu proyecto

Domina la estructura completa del package.json. Aprende qué significa cada campo, cuáles son obligatorios, cuáles opcionales y cómo configurarlo para proyectos profesionales.

¿Cuánto sabes de NPM?

📘 Teoría

Campos obligatorios: name y version

Estos dos campos son los únicos estrictamente necesarios.

Todo package.json necesita al menos un nombre y una versión. El nombre (name) debe ser único en npm y sigue ciertas reglas: kebab-case (minúsculas con guiones), sin espacios, sin caracteres especiales que puedan causar problemas en URLs. La versión sigue Semantic Versioning (semver), un sistema de tres números: major.minor.patch.

Cuando publicas un paquete en npm, estos dos campos identifican tu paquete de forma única. Dos paquetes con el mismo nombre y versión se consideran el mismo paquete.

name: único en npm, kebab-case
version: major.minor.patch (semver)
Juntos identifican tu paquete unívocamente

Campos descriptivos: description, keywords, author

Información que ayuda a otros a entender y encontrar tu proyecto.

description es una cadena de texto que resume qué hace tu paquete. Aparece en npm search y en la página del paquete. Mantenla concisa pero informativa: 'Librería para parsear fechas en español' es mejor que 'Una herramienta útil'.

keywords es un array de strings que ayuda en la búsqueda. Si publicas un paquete de fechas en español, incluye keywords como ['fechas', 'español', 'i18n', 'date']. author indica el creador con formato 'Nombre (url)'.

license indica bajo qué licencia redistribuyes tu código. MIT es la más común en código abierto. Si no especificas license, npm avisa pero no impide la publicación.

Ejemplo de campos descriptivos

{
  "name": "mi-paquete-fechas",
  "version": "1.0.0",
  "description": "Manipulación de fechas en español con soporte para locale",
  "keywords": ["fechas", "español", "i18n", "date", "moment"],
  "author": "Tu Nombre <tu@email.com> (https://tuweb.com)",
  "license": "MIT"
}

El campo main: punto de entrada

Indica qué archivo se ejecuta cuando alguien hace require() o import.

El campo main especifica el path al archivo JavaScript que se ejecuta cuando alguien incluye tu paquete. Si publicas una librería utils, main debería apuntar al archivo que exporta todas las funciones públicas.

Por convención, el archivo principal suele llamarse index.js, pero puede ser cualquier archivo. Lo importante es que exports lo que los usuarios esperan usar.

Ejemplo de main

{
  "name": "mi-libreria-utils",
  "main": "dist/index.js",
  "module": "dist/index.mjs"
}

Scripts: automatización integrada

Los scripts definen comandos ejecutables con npm run.

El objeto scripts contiene comandos que puedes ejecutar con npm run. Hay scripts predefinidos (install, publish, test) que npm ejecuta automáticamente en ciertos momentos, y scripts personalizados que tú defines.

Los scripts personalizados más comunes son start, build, test, lint y dev. npm run muestra una lista de todos los scripts disponibles, incluyendo los que añade npm lifecycle.

Ejemplo de scripts

{
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js",
    "build": "webpack --mode production",
    "test": "jest",
    "lint": "eslint src/",
    "prepublishOnly": "npm run build"
  }
}

El campo engines: control de versiones de Node

Especifica qué versiones de Node y npm soporta tu proyecto.

El campo engines indica la versión de Node y npm que tu proyecto requiere. Aunque npm no impide instalación en versiones no soportadas, herramientas como pnpm o engines Strict lo respetan.

Usa operadores de semver: '>=16.0.0', '21.0.0', '^18.0.0' (cualquier patch dentro de la misma major). Considera qué versiones usan tus usuarios objetivo.

Ejemplo de engines

{
  "engines": {
    "node": ">=18.0.0 <21.0.0",
    "npm": ">=9.0.0"
  },
  "engineStrict": true
}

Repository y bugs: conexión con el código fuente

Permite a usuarios y herramientas encontrar tu código y reportar problemas.

El campo repository indica dónde está el código fuente. Puede ser GitHub, GitLab, Bitbucket o cualquier otro hosting. El formato es 'tipo:url', por ejemplo: 'git:github.com/usuario/proyecto.git'.

El campo bugs debe contener una URL (a issues) y opcionalmente un email. npm show usa esta info para mostrar en 'npm home' y para reportar bugs.

Ejemplo de repository y bugs

{
  "repository": {
    "type": "git",
    "url": "git+https://github.com/usuario/mi-proyecto.git"
  },
  "bugs": {
    "url": "https://github.com/usuario/mi-proyecto/issues",
    "email": "soporte@mi-proyecto.com"
  },
  "homepage": "https://mi-proyecto.com"
}