Módulos: CommonJS, ES Modules, fs y path

1.Por qué existen los módulos

Un programa real no cabe en un solo archivo. Se divide en módulos: archivos pequeños, cada uno con una responsabilidad, que se exportan piezas (funciones, objetos, constantes) y se importan unos a otros. Así el código se ordena, se reutiliza y se prueba por partes.

En Node conviven dos sistemas de módulos, por razones históricas:

2.CommonJS: require y module.exports

Imagina dos archivos en la misma carpeta. En mates.js decides qué se comparte con module.exports; en app.js lo recoges con require:

function sumar(a, b) {
  return a + b;
}

function multiplicar(a, b) {
  return a * b;
}

module.exports = { sumar, multiplicar };

const { sumar, multiplicar } = require("./mates.js");

console.log(sumar(2, 3));
console.log(multiplicar(4, 5));

5
20

Lo que no está dentro de module.exports queda privado en su archivo. Las rutas que empiezan por ./ son relativas al archivo actual. Los nombres sin ruta (require("fs")) buscan módulos integrados o paquetes instalados.

3.ES Modules: import y export

Con ES Modules el mismo ejemplo se escribe con export e import. Primero se activa el modo módulo en package.json:

{
  "name": "curso-node",
  "version": "1.0.0",
  "type": "module"
}

export function sumar(a, b) {
  return a + b;
}

export function multiplicar(a, b) {
  return a * b;
}

// Una exportación por defecto: solo puede haber una por archivo
export default function restar(a, b) {
  return a - b;
}

import restar, { sumar, multiplicar } from "./mates.js";

console.log(sumar(2, 3));
console.log(multiplicar(4, 5));
console.log(restar(9, 4));

5
20
5

Diferencias que te encontrarás

• En ESM no existen require, module, __dirname ni __filename. Para saber la carpeta del archivo actual usa import.meta.dirname y import.meta.filename (disponibles en Node 20.11 y posteriores).
• Puedes usar await directamente en el nivel superior del archivo, sin envolverlo en una función async.
• Un archivo es CommonJS o ESM: no mezcles require con import en el mismo archivo.

4.Módulos integrados y el prefijo node:

Node incluye muchos módulos sin necesidad de instalar nada: fs (archivos), path (rutas), http (servidores), os (sistema), crypto (criptografía)… Se importan con el prefijo node:, que deja claro que son del propio Node y no paquetes de terceros:

import fs from "node:fs";
import { readFile, writeFile } from "node:fs/promises";
import path from "node:path";
import os from "node:os";

Por ahora usarás dos de ellos: fs para leer y escribir archivos y path para construir rutas. En la lección 4 llegará el servidor web.

5.Leer y escribir archivos con fs

El módulo fs (file system) trabaja con archivos y carpetas. Hoy se usa su versión basada en promesas, node:fs/promises, con await. Crea un archivo notas.txt con dos líneas y este script leer.js:

Comprar pan
Estudiar Node

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

const texto = await readFile("notas.txt", "utf8");
console.log(texto);
console.log("Líneas:", texto.split("\n").length);

Comprar pan
Estudiar Node
Líneas: 2

El segundo argumento, "utf8", indica que quieres texto. Sin él, readFile devuelve un Buffer (bytes sin interpretar). Escribir es igual de directo:

import { writeFile, appendFile } from "node:fs/promises";

// Crea el archivo o lo SOBRESCRIBE si ya existe
await writeFile("saludo.txt", "Hola desde Node\n", "utf8");

// Añade al final sin borrar lo anterior
await appendFile("saludo.txt", "Otra línea\n", "utf8");

console.log("Archivos escritos");

Archivos escritos

Archivos JSON: la base de datos más simple

Como JSON es texto, guardar y leer datos estructurados es combinar fs con JSON.stringify y JSON.parse:

import { readFile, writeFile } from "node:fs/promises";

const tareas = [
  { id: 1, texto: "Instalar Node", hecha: true },
  { id: 2, texto: "Aprender módulos", hecha: false }
];

// null, 2 → JSON con sangría, fácil de leer
await writeFile("tareas.json", JSON.stringify(tareas, null, 2), "utf8");

const leidas = JSON.parse(await readFile("tareas.json", "utf8"));
console.log(leidas.length, "tareas;", "primera:", leidas[0].texto);

2 tareas; primera: Instalar Node

Cuando el archivo no existe

Si pides un archivo que no existe, la promesa se rechaza con un error cuyo código es ENOENT (no such file or directory). Se atrapa con try/catch:

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

try {
  const texto = await readFile("no-existe.txt", "utf8");
  console.log(texto);
} catch (error) {
  if (error.code === "ENOENT") {
    console.log("Ese archivo no existe");
  } else {
    throw error; // otro problema: no lo ocultes
  }
}

Ese archivo no existe

6.Construir rutas con path

Las rutas se escriben distinto según el sistema: datos/notas.txt en macOS y Linux, datos\notas.txt en Windows. Concatenar textos a mano con "/" se rompe tarde o temprano. El módulo path resuelve esas diferencias:

import path from "node:path";

const ruta = path.join("datos", "2026", "notas.txt");
console.log(ruta);
console.log(path.basename(ruta));
console.log(path.basename(ruta, ".txt"));
console.log(path.extname(ruta));
console.log(path.dirname(ruta));

datos/2026/notas.txt
notas.txt
notas
.txt
datos/2026

La salida de arriba es la de macOS y Linux; en Windows las barras aparecen como \. Resumen:

7.Argumentos de la línea de comandos: process.argv

Un script puede recibir datos al ejecutarlo: node saludo.js Ana. Esos datos llegan en process.argv, un array cuyos dos primeros elementos son la ruta de node y la del script; los tuyos empiezan en la posición 2.

console.log(process.argv);

const [nombre = "Mundo"] = process.argv.slice(2);
console.log(`Hola, ${nombre}`);

node saludo.js Ana

[
  '/usr/local/bin/node',
  '/home/ana/curso-node/saludo.js',
  'Ana'
]
Hola, Ana

Con slice(2) te quedas solo con lo que escribió la persona. Para terminar el programa indicando que hubo un problema, asigna un código de salida: 0 significa éxito y cualquier otro número, error.

const [archivo] = process.argv.slice(2);

if (!archivo) {
  console.error("Uso: node validar.js <archivo>");
  process.exitCode = 1; // termina con error cuando acabe lo pendiente
} else {
  console.log("Procesando", archivo);
}

Ahora la parte práctica: un analizador de argumentos de estilo --clave valor es JavaScript puro y puedes probarlo aquí mismo, en el navegador.

8.Errores frecuentes

• Olvidar la extensión en ESM: import ... from "./mates" falla con ERR_MODULE_NOT_FOUND. Escribe "./mates.js".
• Mezclar require e import: dentro de un archivo ESM, require no existe.
• Olvidar "type": "module" y obtener Cannot use import statement outside a module.
• Usar __dirname en ESM: no existe. Usa import.meta.dirname.
• Olvidar await al leer un archivo: obtienes Promise { <pending> } en lugar del texto.
• Sobrescribir sin querer con writeFile: si solo quieres añadir al final, usa appendFile.
• Contar mal los argumentos: process.argv[0] y [1] no son tuyos; usa slice(2).

9.Glosario