npm y package.json

1.Qué es npm y qué es un paquete

Casi nadie programa todo desde cero. Para casi cualquier necesidad (un servidor web, validar datos, manejar fechas) alguien ya escribió y publicó una biblioteca. Esas bibliotecas se llaman paquetes y viven en un registro público. npm (Node Package Manager) es la herramienta que viene con Node y que sirve para:

1. Descargar paquetes en tu proyecto (npm install).
2. Anotar qué paquetes usa tu proyecto, y en qué versión, en package.json.
3. Ejecutar comandos del proyecto con atajos (npm run).

Ya usaste npm en React cuando escribiste npm install y npm run dev: lo que aprendes aquí es lo que hay detrás de esos comandos.

2.package.json por dentro

El package.json es la ficha del proyecto. Es un archivo JSON (comillas dobles, sin comas finales, sin comentarios) con esta pinta:

{
  "name": "mi-api",
  "version": "1.0.0",
  "description": "Mi primera API con Node",
  "type": "module",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "node --watch index.js"
  },
  "dependencies": {
    "express": "^5.1.0"
  },
  "devDependencies": {
    "prettier": "^3.3.0"
  },
  "engines": {
    "node": ">=20"
  }
}

3.Instalar y quitar paquetes

Dentro de la carpeta del proyecto (donde está el package.json) instalas un paquete con:

npm install express

added 65 packages, and audited 66 packages in 2s

found 0 vulnerabilities

Tu número de paquetes será distinto: un paquete suele depender de otros, y npm los descarga todos. Después del comando ocurren tres cosas:

• Aparece (o crece) la carpeta node_modules/ con el código de todos los paquetes.
• Se añade express a dependencies en package.json.
• Se crea o actualiza package-lock.json, que fija la versión exacta de cada paquete instalado.

Una vez instalado, lo usas desde tu código con un import:

import express from "express";

console.log(typeof express);

function

4.Versiones: MAYOR.MENOR.PARCHE

Los paquetes usan versionado semántico: tres números separados por puntos, por ejemplo 5.1.2.

En package.json las versiones llevan un símbolo delante que indica qué actualizaciones acepta npm:

El símbolo ^ es el que npm escribe por defecto. Para ver la idea en acción, aquí tienes una versión simplificada de la comparación, en JavaScript puro:

5.Scripts: atajos para tus comandos

Dentro de scripts defines nombres de comandos y lo que ejecutan. Así, quien llegue a tu proyecto no necesita saber cómo se arranca: solo escribe npm run más el nombre.

"scripts": {
  "start": "node index.js",
  "dev": "node --watch index.js",
  "formatear": "prettier --write ."
}

npm run dev

> mi-api@1.0.0 dev
> node --watch index.js

Servidor escuchando…

Dos nombres tienen atajo y se pueden ejecutar sin run: npm start y npm test. Para cualquier otro nombre debes escribir npm run nombre. Y si escribes solo npm run, verás la lista de scripts disponibles.

Los programas instalados como dependencia (por ejemplo prettier) están disponibles dentro de los scripts sin escribir su ruta. Fuera de un script, se ejecutan con npx:

npx prettier --check .

npx ejecuta el programa de un paquete: si está en tu proyecto usa esa copia; si no, lo descarga temporalmente para esa ejecución.

6.node_modules y .gitignore

La carpeta node_modules/ puede contener miles de archivos y pesar cientos de megabytes. Pero es totalmente reproducible: con package.json y package-lock.json, npm install la vuelve a crear. Por eso nunca se sube a Git. Se excluye con un archivo .gitignore en la raíz del proyecto:

node_modules/
.env
*.log

Cada línea es un patrón de archivos que Git debe ignorar:

• node_modules/: las dependencias descargadas.
• .env: variables privadas como contraseñas o claves (lo verás en la lección 6).
• *.log: archivos de registro.

Si un día algo se comporta de forma extraña tras actualizar paquetes, el remedio clásico es borrar node_modules y ejecutar npm install otra vez.

7.Leer un package.json con JavaScript

Como package.json es JSON, puedes leerlo con JSON.parse (lección 2) y trabajar con él como con cualquier objeto. Este editor lo hace en tu navegador con un texto de ejemplo:

8.Errores frecuentes

• Subir node_modules a Git: engorda el repositorio sin necesidad. Añádelo a .gitignore antes de tu primer commit.
• Ejecutar npm install en la carpeta equivocada: crea otro node_modules y otro package.json donde no querías. Comprueba que estás junto al package.json.
• Una coma de más en package.json: el archivo es JSON estricto y npm lo rechaza.
• Escribir npm dev: solo start y test tienen atajo. Lo correcto es npm run dev.
• Editar package-lock.json a mano: lo gestiona npm; si lo rompes, bórralo y ejecuta npm install.
• Poner en dependencies algo que solo usas al desarrollar: usa npm install -D para las herramientas de desarrollo.
• Ignorar npm audit: revísalo de vez en cuando; muchas vulnerabilidades se arreglan actualizando.

9.Glosario