Cerrábamos el módulo 2 con el contrato de Tienda Aroma completo sobre el papel: 24 URIs, métodos con su idempotencia resuelta, catálogo de errores, representaciones JSON, paginación, versionado y documentación. Ni una línea de servidor. Este módulo cumple ese contrato con Node.js 20 y Express, y como en cualquier obra seria, se empieza por los cimientos: preparar la máquina, crear el proyecto, elegir y entender cada dependencia, definir la estructura de carpetas que sostendrá ocho lecciones de código y aislar la configuración en variables de entorno. Es la lección menos vistosa del módulo y la que más problemas evita: casi todos los atascos de un principiante con Node vienen de una versión equivocada, un import que el proyecto no admite o un secreto escrito a fuego en el código. Al terminar tendrás el esqueleto del proyecto listo para que la siguiente lección lo arranque; todavía no habrá servidor, y eso es intencionado.

1. Qué vamos a construir y con qué
2. Node.js 20 LTS: instalación y verificación
3. Gestores de versiones: nvm y fnm
4. npm y npx
5. Creación del proyecto con npm init
6. Anatomía de package.json
7. ESM frente a CommonJS y "type": "module"
8. Versionado semántico en las dependencias: ^ y ~
9. package-lock.json, npm ci frente a npm install
10. dependencies frente a devDependencies
11. Las dependencias del curso, una por una
12. Los scripts npm del proyecto
13. La estructura de carpetas
14. Configuración con variables de entorno
15. .gitignore e inicialización de Git
16. Editor y herramientas de trabajo
17. Comprobación final del entorno

Durante las ocho lecciones de este módulo vamos a construir un único proyecto que crece. No habrá ejemplos sueltos que se tiran a la basura: cada lección parte del estado en que la dejó la anterior y dice explícitamente qué ficheros crea y cuáles modifica.

La pila técnica queda fijada aquí y no cambia:

Una nota sobre el idioma: como fijamos en la guía de estilo de 02-01, el código y los comentarios van en español. Verás obtenerCafes, precioEuros, repositorioCafes o manejadorErrores, y los ficheros del proyecto se llaman rutas/cafes.js o servicios/pedidos.js. Solo mantienen su nombre en inglés los que impone la herramienta: package.json, .env, node_modules.

Node.js es el entorno que ejecuta JavaScript fuera del navegador. Las versiones pares (18, 20, 22) son LTS (Long Term Support): reciben correcciones durante unos tres años y son las que se usan en producción. Las impares son experimentales.

Lo primero es ver qué hay instalado:

Si node --version responde v20.x.x, ya tienes lo necesario. Si responde v16.x.x o el comando no existe, sigue leyendo. Necesitamos 20 o superior por tres motivos concretos que usaremos en este módulo:

• node --watch: recarga automática del servidor al guardar, sin nodemon.
• node:test y node --test: runner de pruebas integrado (03-08).
• node --env-file: carga de ficheros .env sin librería (desde 20.6).

Podrías instalar Node desde nodejs.org y terminar. No lo hagas. Un instalador deja una única versión global, y en cuanto trabajes en dos proyectos —uno en Node 18 y otro en Node 20— tendrás un problema que se resuelve desinstalando y reinstalando. Un gestor de versiones permite tener varias a la vez y cambiar de una a otra en segundos, incluso por carpeta.

Los dos habituales:

Instalación de nvm en Linux o macOS:

Uso diario:

Un detalle muy práctico: si creas un fichero .nvmrc en la raíz del proyecto con el contenido 20, cualquiera que clone el repositorio puede ejecutar nvm use y obtener la versión correcta sin preguntar. Vamos a añadirlo:

Con fnm los comandos son casi idénticos (fnm install 20, fnm use 20) y además lee el .nvmrc automáticamente al entrar en la carpeta si lo configuras con --use-on-cd.

Al instalar Node vienen dos comandos que conviene no confundir:

npx es especialmente útil para herramientas de un solo uso (generadores, migradores) y para ejecutar binarios que están en node_modules/.bin sin escribir la ruta completa.

Existen alternativas a npm —pnpm (más rápido y ahorra disco), yarn, bun—, y son perfectamente válidas. Este curso usa npm porque viene con Node y no añade un requisito más.

Creamos la carpeta y la inicializamos:

• mkdir crea el directorio del proyecto. El nombre en kebab-case es la convención de npm.
• npm init -y genera un package.json con valores por defecto sin hacer preguntas. Sin -y, npm pregunta nombre, versión, descripción, etc. de forma interactiva.

El resultado es un package.json mínimo:

package.json es la ficha de identidad del proyecto: quién es, qué necesita para funcionar y cómo se ejecuta. Vamos a sustituirlo por la versión definitiva del curso, campo a campo:

Qué significa cada campo:

Node arrastra dos sistemas de módulos y hay que elegir uno conscientemente, porque mezclarlos es la primera fuente de errores incomprensibles.

Tienda Aroma usa ESM. Es el estándar del lenguaje, funciona igual en el navegador y en el servidor, y permite await en el nivel superior de un fichero, algo que agradeceremos al abrir la base de datos en 03-05.

Las dos consecuencias prácticas que más despistan al principio:

Fíjate también en el prefijo node: (node:url, node:path, node:fs). Es la forma moderna y explícita de importar módulos internos de Node, y evita que un paquete malicioso llamado path en npm suplante al módulo del sistema. Úsalo siempre.

Cuando instalas un paquete, npm escribe en package.json un rango de versiones aceptables, no una versión exacta. Recuerda SemVer de 02-07: MAYOR.MENOR.PARCHE.

El valor por defecto de npm es ^, y es un compromiso razonable: recibes correcciones de fallos y funcionalidades nuevas sin cambios rompedores, siempre que el autor respete SemVer. Nunca uses *: significa "instálame lo que sea", y un día tu build romperá sin que hayas tocado nada.

Si package.json dice ^4.18.2, dos personas que instalen en fechas distintas pueden acabar con 4.18.2 y 4.19.1. Eso es exactamente lo que produce el clásico "en mi máquina funciona". La solución es package-lock.json: un fichero generado automáticamente que registra la versión exacta de cada paquete instalado y de cada dependencia de sus dependencias, con su hash de integridad.

Reglas de oro:

• package-lock.json se versiona en Git. Siempre. No es un fichero temporal.
• No se edita a mano jamás.

Y de ahí la diferencia entre los dos comandos de instalación:

Regla práctica: en tu portátil, npm install; en el pipeline de CI y en el servidor, npm ci (lo veremos en 05-05). Si npm ci falla porque el lock no concuerda con package.json, eso es una virtud, no un fallo: te está avisando de que alguien tocó las dependencias sin regenerar el lock.

La distinción no es cosmética: reduce el tamaño de la imagen de despliegue y, sobre todo, la superficie de ataque. Un linter no debería existir siquiera en el servidor de producción. El error inverso —poner en devDependencies algo que el servidor usa en tiempo de ejecución— produce un ERR_MODULE_NOT_FOUND que solo aparece al desplegar.

Instalamos primero las de producción:

Y las de desarrollo:

Dos aclaraciones sobre elecciones que llaman la atención:

• express@4 y no 5. Express 5 ya es estable, pero la inmensa mayoría del código, la documentación y las respuestas que encontrarás son de la 4. Además, la 4 tiene una carencia muy didáctica —no captura los errores de funciones async— que nos obliga a entender de verdad el manejo de errores en 03-07. Diremos en su momento qué cambia con la 5.
• bcrypt y no bcryptjs. bcrypt es una extensión nativa (se compila al instalar) y es más rápida. Si su compilación falla en tu máquina —suele pasar en Windows sin herramientas de compilación—, bcryptjs es un sustituto en JavaScript puro con la misma API: npm install bcryptjs y cambia el import.

No necesitamos nodemon: node --watch hace lo mismo desde Node 18. Ni cors, helmet o express-rate-limit, que llegarán en el módulo 4 cuando toque endurecer la API.

Los scripts son la interfaz de la que dispone cualquiera que llegue al repositorio. Lo primero que hace un desarrollador nuevo es mirar scripts para saber cómo se arranca el proyecto.

Detalle de npm que confunde: start y test son scripts "conocidos" y se invocan sin run (npm start, npm test); el resto necesita run (npm run dev). Ambos funcionan con run, así que en la duda, escribe npm run.

Aquí está la decisión de arquitectura de todo el módulo. Vamos a organizar el código por capas, con una responsabilidad clara por carpeta:

¿Por qué tantas carpetas para una API pequeña? Porque cada frontera resuelve un problema real, y todas se cobran su beneficio dentro de este mismo módulo:

• Rutas separadas de controladores: el mapa de URIs de 02-02 se lee de un vistazo en un fichero, sin lógica en medio.
• Controladores separados de servicios: el servicio no toca req ni res, así que se puede probar sin levantar un servidor (03-08) y reutilizar desde un script de línea de comandos o una tarea programada.
• Servicios separados de repositorios: en 03-05 sustituimos el almacén en memoria por SQLite sin tocar una sola línea de los controladores ni de los servicios. Esa es la prueba de que la frontera vale la pena.
• Middleware aparte: validación, autenticación y errores son transversales; si viven dentro de las rutas, acaban duplicados en veinte sitios.

El flujo de una petición, de fuera hacia dentro, será siempre el mismo:

Y la regla que lo mantiene sano: las flechas nunca van hacia atrás. Un repositorio no llama a un servicio, y un servicio no importa nada de Express.

El puerto, la ruta de la base de datos y el secreto de firma de los JWT no pueden estar escritos en el código. Cambian entre tu portátil, el entorno de pruebas y producción, y algunos son secretos.

El estándar de facto es la metodología Twelve-Factor App: la configuración vive en el entorno, no en el código. En Node se lee con process.env.

Creamos el fichero .env en la raíz:

Y .env.example, que sí se versiona, con las mismas claves pero sin valores reales:

Este segundo fichero es documentación ejecutable: quien clone el repositorio hace cp .env.example .env, rellena y arranca. Sin él, la única forma de saber qué variables hacen falta es leer todo el código o esperar a que reviente.

Leer process.env.PUERTO disperso por todo el código es mala idea: no sabes qué variables existen, no hay valores por defecto centralizados y un error tipográfico produce undefined silencioso. Centralizamos la lectura en un único módulo que además valida al arrancar y falla ruidosamente si algo falta:

Línea a línea, lo importante:

• import 'dotenv/config' ejecuta dotenv por su efecto secundario: lee .env y vuelca sus claves en process.env. Debe ocurrir antes de leer cualquier variable, y por eso está en la primera línea del primer módulo que se importa.
• obligatoria() lanza un error si la variable falta. Esto es deliberado: preferimos que el proceso no arranque a que arranque con jwtSecreto === undefined y firme tokens inseguros durante semanas.
• numerica() convierte y comprueba. Recuerda que todas las variables de entorno son cadenas de texto: process.env.PUERTO es "3000", no 3000.
• Object.freeze impide reasignaciones accidentales.

A partir de ahora, cualquier fichero que necesite configuración hace import { entorno } from '../config/entorno.js' y usa entorno.puerto. Nadie más toca process.env.

En 03-04 conoceremos Zod y verás que este fichero podría escribirse con un esquema de cinco líneas. Lo dejamos en JavaScript puro a propósito: la configuración se valida antes de que exista nada más, y conviene que no dependa de terceros.

Como curiosidad útil: desde Node 20.6 existe node --env-file=.env src/servidor.js, que hace el trabajo de dotenv sin instalar nada. Mantenemos dotenv porque funciona igual en cualquier versión y en las herramientas de pruebas.

El fichero .env no se sube nunca a Git. Un secreto subido a un repositorio se considera comprometido para siempre, aunque borres el commit: queda en el historial, en los clones de tus compañeros y en las cachés de la plataforma. Rotarlo es la única solución, y es mucho más caro que escribir bien el .gitignore.

Observa que .env.example no está ignorado (solo lo está .env), que es justo lo que queremos. Y que package-lock.json tampoco: es un fichero que debe viajar con el proyecto.

Inicializamos el repositorio:

Antes de confirmar, verifica con git status que no aparece .env en la lista de ficheros añadidos. Si aparece, el .gitignore está mal o el fichero ya estaba indexado: git rm --cached .env lo saca del índice sin borrarlo del disco.

Cualquier editor sirve, pero VS Code es el más común en el ecosistema Node y tiene integración directa con las herramientas del curso. Extensiones recomendadas: ESLint, Prettier - Code formatter y REST Client (permite lanzar peticiones desde un fichero .http, muy cómodo para probar la API sin salir del editor).

ESLint analiza el código sin ejecutarlo y detecta variables sin usar, await olvidados o comparaciones sospechosas. Configuración plana (la moderna, eslint.config.js):

• js.configs.recommended activa el conjunto de reglas razonables que mantiene el propio ESLint.
• sourceType: 'module' le dice a ESLint que el código es ESM (coherente con "type": "module").
• argsIgnorePattern: '^_' permite argumentos sin usar si empiezan por guion bajo. Lo necesitaremos: el middleware de errores de Express obliga a declarar cuatro parámetros aunque no uses el último (03-07).
• eqeqeq obliga a === en lugar de ==.
• configPrettier va el último y desactiva las reglas de estilo que se pisarían con Prettier.

Necesita un paquete más: npm install --save-dev @eslint/js.

Prettier no opina sobre si el código es correcto, solo sobre cómo se ve, y elimina para siempre las discusiones sobre comillas y comas:

Guarda esto como .prettierrc.json. Con la extensión de VS Code y "Format on Save" activado, el formato deja de ser un tema de conversación.

node --watch vigila los ficheros importados por el punto de entrada y reinicia el proceso al guardar. No confundir con node --watch-path, que vigila una carpeta concreta, ni con el hot reload del navegador: aquí el proceso se reinicia entero, así que el estado en memoria se pierde. En 03-02 y 03-03 los cafés viven en memoria, y notarás que un reinicio los devuelve a su valor inicial. Es normal y desaparece en 03-05 con SQLite.

Durante todo el módulo probaremos con curl, que ya usamos en 01-03. Es universal, se copia y pega en cualquier documentación y no oculta nada:

• -i incluye las cabeceras de respuesta, imprescindible para comprobar Location, Link o Allow.
• -v muestra además la petición completa.
• -s silencia la barra de progreso, útil al encadenar con jq.

Postman es un cliente gráfico con colecciones, entornos y pruebas automatizadas; es una herramienta excelente y le dedicamos entera la lección 05-01. Aquí no lo necesitamos.

El proyecto todavía no tiene servidor —eso es 03-02—, pero sí podemos verificar que los cimientos aguantan. Crea un fichero temporal comprobar.js en la raíz:

Fíjate en number: la conversión de numerica() ha funcionado. Ahora prueba el camino de fallo, que es igual de importante: comenta la línea JWT_SECRETO= de tu .env y vuelve a ejecutar.

El proceso muere inmediatamente con un mensaje que dice exactamente qué falta. Ese es el comportamiento correcto. Restaura el .env y borra comprobar.js.

Estado del proyecto al terminar la lección:

1. ERR_REQUIRE_ESM o Cannot use import statement outside a module. Falta "type": "module" en package.json, o estás usando require en un proyecto ESM. Decide un sistema y respétalo en todo el proyecto.

2. ERR_MODULE_NOT_FOUND con un fichero que sí existe. En ESM la extensión .js es obligatoria en las importaciones relativas. ./servicios/cafes falla; ./servicios/cafes.js funciona.

3. Subir .env a Git. El error más caro de esta lección. Escribe el .gitignore antes del primer git add. Si ya ha ocurrido, no basta con borrar el fichero: hay que rotar el secreto.

4. npm install en el servidor de producción. Puede instalar versiones distintas de las que probaste. Usa siempre npm ci, que respeta el lock al pie de la letra.

5. Añadir package-lock.json al .gitignore. Se ve más de lo que parece y anula toda la reproducibilidad. El lock se versiona.

6. Instalar globalmente (npm install -g) las dependencias del proyecto. Lo global no queda registrado en package.json, así que funciona en tu máquina y en ninguna otra. Solo se instalan globalmente herramientas de sistema, y a menudo ni eso: npx las ejecuta sin instalar.

7. Leer process.env desde media docena de ficheros. Céntralo en config/entorno.js. El día que una variable cambie de nombre, tocarás un sitio y no seis.

8. Confundir la versión de package.json con la versión de la API. "version": "1.0.0" es del artefacto de software; /v1 es del contrato. Pueden avanzar por separado: 1.4.7 sigue sirviendo /v1 (02-07).

Consejo: haz un commit al final de cada lección de este módulo. Si algo se rompe en 03-05, git diff te dirá en treinta segundos qué cambió respecto al estado bueno.

Añade a la configuración una variable nueva, LIMITE_PAGINA_MAXIMO, que fije el máximo de elementos por página decidido en 02-06. Debe ser numérica, opcional, con valor por defecto 100, y el arranque debe fallar si alguien escribe un valor no entero o mayor que 1000. Modifica .env, .env.example y src/config/entorno.js.

Un compañero clona el repositorio y ejecuta npm start. Obtiene:

Explica qué ha pasado exactamente, por qué es el comportamiento deseable y qué dos pasos debe seguir. Después, propón una mejora del mensaje de error para que sea autoexplicativo.

Clasifica estos paquetes en dependencies o devDependencies y justifica cada uno en una frase: express, supertest, dotenv, prettier, better-sqlite3, eslint, jsonwebtoken. Después indica qué ocurriría exactamente si dotenv acabara por error en devDependencies y se desplegara con npm ci --omit=dev.

Solución 1

En .env y .env.example:

En src/config/entorno.js, una función nueva y un campo más:

Reutilizamos numerica(), que ya rechaza los valores no enteros, y solo añadimos la comprobación de rango. Con LIMITE_PAGINA_MAXIMO=5000 el arranque aborta con un mensaje explícito, que es exactamente lo que queremos: un límite de paginación mal configurado es un problema de disponibilidad (02-06), no un detalle menor.

Solución 2

Qué ha pasado: al clonar solo ha obtenido .env.example, porque .env está en .gitignore y no viaja con el repositorio. Sin .env, dotenv no encuentra nada que cargar, process.env.JWT_SECRETO es undefined y la función obligatoria() aborta el arranque.

Por qué es deseable: es un fail fast. La alternativa sería arrancar con jwtSecreto === undefined, y entonces jsonwebtoken firmaría (o fallaría) en la primera petición de login, en producción, con un error críptico y a las tres de la mañana. Detectar el problema en el segundo cero, en el arranque, con el nombre exacto de la variable, es infinitamente más barato.

Los dos pasos: cp .env.example .env y rellenar JWT_SECRETO con una cadena larga y aleatoria, por ejemplo con node -e "console.log(require('crypto').randomBytes(48).toString('hex'))".

Mensaje mejorado:

Un buen mensaje de error no describe el problema: describe la solución.

Solución 3

Si dotenv cayera en devDependencies: npm ci --omit=dev no lo instalaría, y import 'dotenv/config' en src/config/entorno.js lanzaría ERR_MODULE_NOT_FOUND en el arranque. El proceso moriría antes de escuchar en el puerto. Es un fallo ruidoso e inmediato, lo cual es una suerte; el caso verdaderamente peligroso es el de un paquete que solo se importa en una ruta poco frecuente, porque entonces el despliegue parece correcto y revienta días después. Merece la pena señalar un matiz: en producción real muchas veces no hay .env en absoluto —las variables las inyecta el orquestador—, así que hay quien argumenta que dotenv es solo de desarrollo. Si tu arranque lo importa incondicionalmente, es una dependencia de producción y punto.

El entorno está montado y, más importante, cada decisión está tomada con criterio y no por inercia: Node.js 20 LTS gestionado con nvm para poder convivir con otros proyectos, ESM en lugar de CommonJS con las consecuencias que eso tiene en cada import, dependencias con rangos ^ respaldadas por un package-lock.json que sí se versiona, npm ci reservado para CI y producción, y una separación clara entre lo que la aplicación necesita para ejecutarse y lo que solo usamos nosotros al desarrollar. Sabes qué aporta cada uno de los diez paquetes instalados y en qué lección aparecerá.

Sobre todo, has fijado dos cosas que condicionan el resto del módulo. La primera es la estructura por capas —rutas, controladores, servicios, repositorios— que en 03-05 permitirá cambiar el almacén en memoria por SQLite sin tocar la lógica, y en 03-08 permitirá probar los servicios sin levantar un servidor. La segunda es la configuración en el entorno: un .env que nunca se versiona, un .env.example que documenta, y un src/config/entorno.js que valida al arrancar y prefiere no arrancar antes que funcionar a medias.

Tenemos el esqueleto y ni una sola línea que responda a una petición. En 03-02, Creación de un servidor básico, eso cambia: veremos qué es realmente Express y qué es un middleware con su firma (req, res, next), separaremos app.js de servidor.js —una decisión que parece caprichosa hasta que llegan las pruebas de 03-08—, montaremos el Router bajo /v1 materializando el versionado en la ruta que decidimos en 02-07, y devolveremos los primeros cafés reales, caf_001 y caf_002, con el envoltorio {"datos": [...], "total": n} del contrato.