El entorno

Tres horas. Media hora para entender qué desaparece y qué aparece al sacar JavaScript del navegador, y dos horas y media montando un proyecto de Node con su configuración fuera del código y sus responsabilidades separadas.

Se explica

25 minutos · conceptos y demostración

El lenguaje es el mismo; cambia todo lo que lo rodea. Hoy se inventaría qué se pierde, qué se gana, y por qué la parte de tu código que no sabía nada de la página es la única que viaja intacta.

Un motor sin navegador

Node.js es el motor de JavaScript de Chrome, sacado del navegador y empaquetado como un programa que puedes ejecutar en tu máquina. Alrededor le añadieron lo que un navegador no le deja hacer: acceso al sistema de ficheros, a la red y a los procesos del sistema.

node --version
node -e "console.log('Hola desde Node')"
node src/hola.js

document.querySelector("h1");   // ReferenceError: document is not defined
window.localStorage;            // ReferenceError
alert("Hola");                  // ReferenceError

No están rotos: no tienen sentido. No hay documento ni ventana. Todo el módulo catalogo.js de la UD3, en cambio, funciona aquí sin cambiar una coma, porque solo trabaja con datos. Ese es, otra vez, el premio de haber separado la lógica de la página.

process.argv;              // los argumentos de la llamada
process.env;               // las variables de entorno
process.exit(1);           // terminar con un código
process.cwd();             // desde dónde se ejecutó

Los módulos del sistema se importan con el prefijo node::

import { readFile } from "node:fs/promises";
import path from "node:path";
import http from "node:http";

El prefijo node:

Deja claro que el módulo es del propio Node y no una dependencia descargada. Sin él también funciona, pero con él nadie puede confundir tu importación con un paquete externo instalado por alguien.

Cómo entran los datos

node src/cli.js listar
node src/cli.js buscar teclado
node src/cli.js añadir "Ratón vertical" 39.9

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

console.log(comando);      // "buscar"
console.log(argumentos);   // ["teclado"]

Las dos primeras posiciones son siempre el ejecutable y el fichero, por eso se descartan. Y, como todo lo que entra desde fuera, los argumentos son texto: un precio hay que convertirlo y comprobarlo, igual que hacías con los campos de formulario.

La configuración, en cambio, no entra por argumentos sino por el entorno:

const puerto = Number(process.env.PUERTO ?? 3000);
const entorno = process.env.NODE_ENV ?? "development";

En cuanto haya más de una variable, se pasan por fichero. Desde Node 20 se puede cargar un .env sin instalar nada, y la orden es idéntica en las tres terminales:

node --env-file=.env src/servidor.js

Al repositorio se incorpora .env.example, con las claves y sin los valores. El .env real va al .gitignore.

Cómo sale el resultado

console.log("Resultado");      // salida estándar
console.error("Ha fallado");   // salida de error

process.exit(0);   // todo bien
process.exit(1);   // ha fallado

Código de salida

El número con el que termina un programa. Cero significa éxito; cualquier otro, fallo. Es como se enteran las herramientas que encadenan programas —un script, un sistema de integración continua— de si deben seguir o pararse.

Separar console.log de console.error importa por lo mismo: permite que quien use tu programa redirija los resultados a un fichero y siga viendo los errores.

Dos sistemas de módulos

Para usar ESM basta una línea en package.json:

{ "type": "module" }

Verás muchísimo require por ahí. Funciona, pero es el sistema heredado: si una respuesta de IA o un tutorial te lo dan, tradúcelo en lugar de mezclar los dos.

Dos diferencias prácticas. En ESM no existen __dirname ni __filename, y la extensión es obligatoria en las rutas relativas, igual que en el navegador:

import { dirname } from "node:path";
import { fileURLToPath } from "node:url";

const aqui = dirname(fileURLToPath(import.meta.url));

Estructura por responsabilidad

Se trabaja

150 minutos · montar el proyecto de la unidad

Lo que montes hoy es el esqueleto sobre el que trabajarás las seis sesiones. Los dos últimos pasos comprueban que la separación que has hecho es real y no solo una disposición de carpetas.

Paso 1 · Primeros programas · 30 min

1. Comprueba tu versión de Node; debe ser 22 o superior.
2. Crea src/hola.js que salude e imprima la versión desde process.version.
3. Copia tu catalogo.js de la UD3 y ejecuta sus funciones desde Node.
4. Intenta usar document y anota el error exacto.
5. Imprime process.cwd() ejecutando desde dos carpetas distintas y explica la diferencia.
6. Prueba el modo interactivo —la orden node sin argumentos— con tres expresiones.

Antes de continuar: tus funciones de la UD3 devuelven lo mismo aquí que devolvían en el navegador, y no has tenido que cambiar ni una línea.

Paso 2 · Un programa configurable · 40 min

1. Escribe src/cli.js que acepte los comandos listar, buscar y ayuda.
2. Si no se pasa comando, muestra la ayuda y termina con código 1.
3. Lee de una variable de entorno la ruta del fichero de datos, con un valor por defecto.
4. Convierte y valida los argumentos numéricos.
5. Comprueba el código de salida tras cada ejecución. En Git Bash es echo $?; en PowerShell, $LASTEXITCODE.
6. Crea .env.example y añade .env al .gitignore.

PUERTO=4000 node src/servidor.js           Git Bash, macOS, Linux
$env:PUERTO="4000"; node src/servidor.js   PowerShell
set PUERTO=4000 && node src/servidor.js    cmd de Windows

Paso 3 · Estructurar el proyecto · 40 min

Es el trabajo central de la sesión.

1. Crea la carpeta mi-api/ con package.json y "type": "module".
2. Crea src/ con almacen.js, catalogo.js y cli.js.
3. Mueve ahí tus funciones de la UD3 sin modificarlas.
4. Escribe en un comentario, en cada fichero, la frase que lo describe. Si necesitas dos frases, el fichero hace dos cosas.
5. Calcula la ruta de datos/productos.json a partir de la posición del fichero, no de dónde se ejecute.
6. Comprueba que cli.js funciona llamándolo desde otra carpeta distinta.

El apartado 6 es el que delata el error clásico: una ruta relativa al directorio de trabajo funciona mientras ejecutes desde la raíz del proyecto y falla en cuanto alguien lo llama desde otro sitio.

Paso 4 · Qué sobrevive de la UD4 · 20 min

Recorre tu proyecto del navegador y clasifica cada módulo:

Cuenta cuántos pasan intactos. Ese número es la medida de lo bien separado que estaba tu código, y no depende de lo listo que fuera: depende de si cada módulo sabía solo de lo suyo.

Los dos casos interesantes son formato.js y estado.js. Míralos con cuidado antes de decidir.

Paso 5 · El grafo de dependencias · 20 min

Dibuja qué módulo importa a cuál, con una flecha por import.

1. ¿Alguna flecha va de catalogo.js hacia almacen.js? Si la hay, tu lógica sabe de dónde vienen los datos, y eso es lo que hoy queremos evitar.
2. ¿Hay ciclos?
3. ¿Qué módulo es el único que conoce el sistema de ficheros?
4. Imagina que mañana los datos vienen de una base de datos. Marca en el dibujo todos los ficheros que habría que tocar. Si es más de uno, señala por qué.
5. Guarda el dibujo: en la sesión 5 lo compararás con el del servidor ya montado.

Ampliación si has completado el trabajo

Primero termina y comprueba los cinco pasos. El primer reto trata la configuración como lo que es: una parte del programa que también falla.

Reto 1 · El programa que se niega a arrancar

Un servidor que arranca sin su clave de base de datos no está funcionando: está esperando a fallar en la primera petición, en producción y de madrugada.

1. Escribe un módulo config.js que lea todas las variables de entorno en un solo sitio y las exporte ya convertidas y validadas.
2. Distingue tres clases de variable: las que tienen un valor por defecto razonable, las obligatorias sin valor por defecto, y las opcionales que pueden faltar.
3. Si falta una obligatoria, el programa debe terminar antes de hacer nada, con un mensaje que diga qué variable falta y cómo se define. Usa el código de salida adecuado.
4. Valida también los tipos: un puerto que llega como "abc" debe fallar igual de pronto que uno que falta.
5. Comprueba tu config.js en los cuatro escenarios: todo definido, sin la obligatoria, con el puerto no numérico, y con una variable opcional ausente.
6. Escribe en tres líneas por qué esta comprobación va en el arranque y no en el punto donde se usa cada variable. La respuesta conecta con «validar en el borde» de la UD3.

Reto 2 · Traducir de CommonJS

Este fragmento es el que te va a dar cualquier tutorial antiguo o cualquier respuesta de IA que no le hayas acotado la versión.

const fs = require("fs");
const path = require("path");
const { buscar } = require("./catalogo");

const RUTA = path.join(__dirname, "..", "datos", "productos.json");

function cargar() {
  const texto = fs.readFileSync(RUTA, "utf8");
  return JSON.parse(texto);
}

module.exports = { cargar, RUTA };

1. Tradúcelo a ESM. Hay cuatro cosas que cambiar, y una de ellas no es una traducción directa: __dirname no existe.
2. La función usa la versión síncrona de la lectura. Averigua qué significa eso en un servidor y reescríbela con la API de promesas. Explica en dos líneas por qué en un programa de terminal daba igual y en un servidor no.
3. Comprueba qué pasa si dejas require en un fichero de un proyecto con "type": "module". Anota el error exacto: lo vas a ver más de una vez.
4. Comprueba también el caso inverso: un import en un proyecto sin "type": "module".
5. Explica en tres líneas por qué no conviene mezclar los dos sistemas en un mismo proyecto, aunque técnicamente haya formas de hacerlo convivir.

Cierre

5 minutos · comprobación y recuerdo