Módulo path de Node.js: path.join vs path.resolve

path.join() une segmentos de ruta con el separador correcto y limpia los .. y las barras duplicadas, pero mantiene el resultado relativo si empezaste con un segmento relativo. path.resolve() hace el mismo trabajo de derecha a izquierda y siempre devuelve una ruta absoluta: parte del directorio de trabajo actual, y cualquier segmento absoluto por el camino reinicia la ruta. Usa join para construir una ruta, y resolve cuando necesites una absoluta.

const path = require('path');

console.log(path.join('users', 'ada', 'notes.txt'));
console.log(path.join('users', 'ada', '..', 'grace', 'todo.txt'));
console.log(path.join('/srv/app/', '/public/', 'index.html'));
console.log(path.join('src', '', 'lib//utils.js'));

Imprimió users/ada/notes.txt, luego users/grace/todo.txt (el .. quitó ada), luego /srv/app/public/index.html y src/lib/utils.js: las barras de más y los segmentos vacíos desaparecen. join nunca trata /public/ como un nuevo comienzo; es solo el siguiente segmento.

path.join vs path.resolve

La diferencia se nota cuando un segmento empieza por / o cuando el primer segmento es relativo:

const path = require('path');

console.log('join:   ', path.join('/srv/app', '/public', 'img'));
console.log('resolve:', path.resolve('/srv/app', '/public', 'img'));

console.log('join:   ', path.join('/srv/app', '../logs'));
console.log('resolve:', path.resolve('/srv/app', '../logs'));

const rel = path.join('public', 'index.html');
const abs = path.resolve('public', 'index.html');
console.log(rel, path.isAbsolute(rel));
console.log(path.isAbsolute(abs), path.relative(process.cwd(), abs));

Con /public en medio, join produjo /srv/app/public/img, mientras que resolve descartó todo lo anterior y produjo /public/img; los dos trataron .. igual. Las dos últimas líneas muestran que join dejó public/index.html relativa, mientras que resolve la hizo absoluta poniendo delante la carpeta actual.

basename, dirname, extname y parse

Estas funciones descomponen una ruta. Solo miran el string: el archivo no tiene por qué existir.

const path = require('path');

const file = '/home/ada/photos/cat.final.jpg';

console.log(path.basename(file));
console.log(path.basename(file, '.jpg'));
console.log(path.dirname(file));
console.log(path.extname(file));
console.log(JSON.stringify(path.parse(file)));

Imprimió cat.final.jpg, cat.final, /home/ada/photos y .jpg: extname toma solo lo que va después del último punto. path.parse lo devuelve todo de una vez (root, dir, base, ext, name), y path.format convierte ese objeto de nuevo en un string.

__dirname y __filename

En un archivo CommonJS, __dirname es la ruta absoluta de la carpeta que contiene el archivo, y __filename la del propio archivo. Una ruta relativa como 'data.json' es relativa a donde el usuario ejecutó node, y se rompe en cuanto alguien lanza tu script desde otra carpeta. Construye las rutas a partir de __dirname:

const fs = require('fs');
const path = require('path');

const configPath = path.join(__dirname, 'config.json');

fs.writeFileSync(configPath, '{ "theme": "dark" }'); // setup
const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));

console.log(path.basename(configPath), config.theme);
console.log(path.relative(__dirname, __filename));

Imprimió config.json dark y index.js. Las rutas completas cambian en cada máquina, y justo por eso las construyes con path.join(__dirname, ...) en lugar de escribirlas a mano.

__dirname en ES modules: import.meta.dirname

Los ES modules no tienen __dirname; usarlo lanza ReferenceError: __dirname is not defined in ES module scope. Desde Node.js 20.11, import.meta.dirname e import.meta.filename los sustituyen:

import path from 'node:path';

const dataFile = path.join(import.meta.dirname, 'data', 'users.json');

console.log(path.basename(import.meta.filename));
console.log(path.relative(import.meta.dirname, dataFile));

Imprimió index.js y data/users.json. En versiones de Node.js anteriores a la 20.11, obtén la carpeta a partir de la URL del módulo: path.dirname(fileURLToPath(import.meta.url)), con fileURLToPath de node:url.

Por qué no unir rutas con strings

'data' + '/' + file funciona en macOS y Linux, pero falla en Windows, donde el separador es \, y no hace nada con los .., las barras dobles o una barra que falta. path usa las reglas del sistema en el que se ejecuta. Puedes ver el resultado de Windows desde cualquier máquina con path.win32:

const path = require('path');

path.posix.join('users', 'ada', 'notes.txt'); // 'users/ada/notes.txt'
path.win32.join('users', 'ada', 'notes.txt'); // 'users\\ada\\notes.txt'
path.sep;                                     // '/' on macOS and Linux, '\\' on Windows

Pasa el resultado de path.join a fs.readFile y el mismo código lee el archivo en cualquier sistema.

Errores comunes

Esperar que extname entienda las extensiones dobles. path.extname('archive.tar.gz') es '.gz', y un archivo oculto como .env no tiene extensión: path.extname('.env') es ''. Comprueba tú mismo el final del nombre cuando te importe el sufijo completo.

Confiar en que join mantenga al usuario dentro de una carpeta. path.join('/srv/app', '../../etc/passwd') es '/etc/passwd'. Antes de leer un archivo cuyo nombre viene de una petición, resuelve la ruta y comprueba que sigue empezando por tu carpeta.