npm y el proyecto

Tres horas. Media hora para entender qué declara un proyecto de Node y qué implica añadirle código de terceros, y dos horas y media construyendo una herramienta de terminal que otra persona pueda usar sin que le expliques nada.

Se explica

25 minutos · conceptos y demostración

Dos asuntos que parecen administrativos y no lo son: cómo se declara un proyecto para que cualquiera pueda arrancarlo, y qué significa de verdad añadirle una línea a dependencies.

La ficha del proyecto

Se genera con npm init -y y se completa a mano:

{
  "name": "mi-api",
  "version": "1.0.0",
  "type": "module",
  "main": "src/servidor.js",
  "scripts": {
    "start": "node src/servidor.js",
    "dev": "node --watch src/servidor.js",
    "cli": "node src/cli.js"
  },
  "engines": { "node": ">=22" },
  "dependencies": {},
  "devDependencies": {}
}

El --watch de Node reinicia el programa solo cuando cambia un fichero; antes hacía falta una dependencia para eso. Los dos guiones de npm run cli -- listar, por su parte, separan los argumentos del script de los de npm.

npm start
npm run dev
npm run cli -- listar

Qué ocurre al instalar

npm install express            # dependencia de ejecución
npm install --save-dev nodemon # solo para desarrollar
npm install                    # todo lo declarado, en un proyecto clonado
npm outdated                   # qué se ha quedado atrás
npm audit                      # vulnerabilidades conocidas

Instalar crea o actualiza tres cosas: la entrada en package.json, el árbol real en node_modules y el package-lock.json.

    4 . 21 . 2
    │    │   └── parche · corrección compatible
    │    └────── menor  · funcionalidad nueva, compatible
    └─────────── mayor  · cambio que rompe

El acento circunflejo es el valor por defecto de npm, y es la razón de que dos instalaciones del mismo package.json en días distintos puedan traer código distinto.

1. ¿Lo resuelve Node de fábrica?
2. ¿Cuántas dependencias arrastra consigo?
3. ¿Se mantiene: última publicación, incidencias abiertas?
4. ¿Sabría hacerlo sin ella si mañana desaparece?

Cada dependencia es código que se ejecuta con tus permisos, que puede tener vulnerabilidades y que alguien tiene que seguir manteniendo. En este proyecto vas a instalar exactamente una.

Una herramienta que otra persona pueda usar

const comandos = {
  listar: listarProductos,
  buscar: buscarProductos,
  añadir: añadirProducto,
  borrar: borrarProducto,
  ayuda: mostrarAyuda
};

const [, , nombre, ...argumentos] = process.argv;
const comando = comandos[nombre];

if (!comando) {
  console.error(`Comando desconocido: ${nombre ?? "(ninguno)"}`);
  mostrarAyuda();
  process.exit(1);
}

try {
  await comando(argumentos);
} catch (error) {
  console.error(`Error: ${error.message}`);
  process.exit(1);
}

Es el objeto de funciones de la sesión 3 de la UD3, ahora con un cometido real. Añadir un comando es añadir una línea.

console.table también existe en Node, y para una lista de objetos es la diferencia entre una salida que se lee y un volcado que no:

console.table(productos.map(({ id, nombre, precio, stock }) => ({
  id, nombre, precio, stock
})));

Se trabaja

150 minutos · el proyecto y su herramienta de terminal

Los dos últimos pasos son los que de verdad evalúan lo anterior: uno pone tu herramienta en manos de otra persona, y el otro comprueba que tu proyecto se reconstruye desde cero.

Paso 1 · La interfaz del proyecto · 30 min

1. Crea el package.json con npm init y añade "type": "module".
2. Define los scripts start, dev y cli.
3. Declara engines con la versión de Node.
4. Comprueba que npm run dev recarga al guardar.
5. Crea el .gitignore con node_modules y .env.
6. Escribe un README.md con las tres órdenes y qué hace cada una.

Paso 2 · Analizar sin instalar · 35 min

1. Busca la ficha de tres paquetes conocidos y anota versión, número de dependencias y fecha de la última publicación.
2. Di qué versiones acepta cada una de estas especificaciones: ^2.4.1, ~2.4.1, 2.4.1. Escribe para cada una dos versiones que sí y una que no.
3. Instala Express, mira qué cambió en los tres sitios, y desinstálalo.
4. Ejecuta npm audit y lee el informe.
5. Aplica a los tres paquetes las cuatro preguntas del diagrama y decide cuáles instalarías.
6. Explica qué pasaría si uno de ellos publicara mañana una versión mayor con cambios incompatibles, teniendo tú un ^ en el package.json.

Paso 3 · El CLI completo · 50 min

Es el trabajo central de la sesión.

1. Implementa listar, buscar, ver, añadir, borrar y ayuda.
2. Valida los argumentos de cada uno con las funciones de la UD3, sin reescribirlas.
3. Escribe mensajes de error que digan qué se esperaba, qué se recibió y cuál es la forma correcta.
4. Devuelve el código de salida correcto en cada caso.
5. Pide confirmación antes de borrar.
6. Usa console.table para las listas y comprueba que la salida se lee.

Antes de continuar: llama a tu programa de cinco formas equivocadas distintas —sin comando, con un comando que no existe, sin argumentos, con un precio que no es número y con uno negativo— y comprueba que las cinco dan un mensaje útil y el código de salida correcto.

Paso 4 · Que lo use otra persona · 20 min

Dale el proyecto a un compañero sin explicarle nada, ni siquiera cómo se arranca.

Anota dónde se atasca sin ayudarle, que es la parte difícil. Cada atasco es un defecto de tu README, de tu ayuda o de tus mensajes, no de la persona.

Corrige lo que salga y vuelve a probarlo con alguien distinto.

Paso 5 · Reconstruir desde cero · 15 min

1. Borra node_modules por completo y ejecuta npm install. Comprueba que todo vuelve.
2. Clona tu propio repositorio en otra carpeta, como si fueras otra persona, y arráncalo siguiendo solo el README.
3. Comprueba qué falta: seguramente el .env, que no está en el repositorio. ¿Explica tu README cómo crearlo a partir del .env.example?
4. Anota cuántos pasos han hecho falta desde clonar hasta ver funcionar el programa. Si son más de tres, mira cuál se puede automatizar en un script.

Ampliación si has completado el trabajo

Primero termina y comprueba los cinco pasos. El primer reto es de seguridad y conviene hacerlo antes de instalar la primera dependencia de la unidad.

Reto 1 · Cuando la dependencia es el problema

Cada paquete que instalas ejecuta código con tus permisos, y lo mismo hacen sus dependencias, y las de sus dependencias.

1. Toma un paquete de uso corriente y averigua cuántos paquetes acabas instalando en total al añadirlo. npm ls --all te lo dice después de instalar. El número suele sorprender.
2. Busca un caso real documentado de un paquete de npm que fue comprometido o retirado, y resume en cinco líneas: qué pasó, cómo llegó a los proyectos que lo usaban y qué lo habría evitado.
3. Explica qué papel juega el package-lock.json en ese escenario, y qué papel no juega. No protege de todo, y conviene saber de qué sí.
4. Busca qué es un typosquatting de paquetes y por qué el nombre que escribes en npm install importa.
5. Aplica las cuatro preguntas del diagrama a Express, que es la única dependencia que instalarás en esta unidad, y escribe si la instalarías. La respuesta es sí; lo que se evalúa es el razonamiento.
6. Escribe en tres líneas qué política seguirías en un proyecto real para decidir cuándo actualizar dependencias, sabiendo que actualizar tarde y actualizar a ciegas son igual de malos.

Reto 2 · Una herramienta que se puede encadenar

Los programas de terminal valen mucho más cuando se combinan con otros. Para eso tienen que respetar unas convenciones.

1. Añade una opción --json que imprima el resultado como JSON sin ningún adorno, para poder pasárselo a otro programa.
2. Comprueba que funciona encadenándolo: redirige la salida a un fichero y ábrelo.
3. Haz que los mensajes informativos vayan a la salida de error y solo el resultado a la estándar. Compruébalo redirigiendo solo una de las dos.
4. Haz que el programa acepte datos por la entrada estándar además de por argumentos, de modo que se le pueda pasar un JSON desde otro proceso.
5. Prueba la cadena completa: un comando que produce datos, el tuyo que los transforma, y la salida guardada en un fichero.
6. Explica en tres líneas por qué «silencio cuando todo va bien» deja de ser una manía en cuanto tu programa forma parte de una cadena automatizada.

Cierre

5 minutos · comprobación y recuerdo

Ver respuestas

1 · Las primeras hacen falta para ejecutar en producción; las segundas, solo para desarrollar y probar.

2 · Para separar los argumentos destinados al script de los de npm.

3 · Cualquier 1.x.x igual o posterior: menores y parches, no la versión mayor.

4 · Para que todas las instalaciones traigan exactamente las mismas versiones; node_modules no se sube porque es reconstruible y depende del sistema.

5 · Explicar cómo se usa y terminar con un código de error.

6 · Porque así se puede encadenar con otros programas sin que su salida estorbe.

---