Node.js path Module: path.join vs path.resolve

path.join() joins path segments with the right separator and cleans up .. and duplicate slashes, but keeps the result relative if you started with a relative segment. path.resolve() does the same work from right to left and always returns an absolute path: it starts from the current working directory, and any absolute segment along the way restarts the path. Use join to build a path, and resolve when you need an absolute one.

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'));

It printed users/ada/notes.txt, then users/grace/todo.txt (the .. removed ada), then /srv/app/public/index.html and src/lib/utils.js: extra slashes and empty segments are gone. join never treats /public/ as a fresh start; it is just the next segment.

path.join vs path.resolve

The difference shows when a segment starts with / or when the first segment is relative:

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));

With /public in the middle, join produced /srv/app/public/img while resolve threw away everything before it and produced /public/img; both handled .. the same way. The last two lines show that join kept public/index.html relative, while resolve made it absolute by putting the current folder in front.

basename, dirname, extname and parse

These take a path apart. They only look at the string: the file does not have to exist.

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)));

It printed cat.final.jpg, cat.final, /home/ada/photos and .jpg: extname takes only the part after the last dot. path.parse returns all of it at once (root, dir, base, ext, name), and path.format turns such an object back into a string.

__dirname and __filename

In a CommonJS file, __dirname is the absolute path of the folder that contains the file, and __filename the file itself. A relative path like 'data.json' is relative to wherever the user ran node, which breaks as soon as someone starts your script from another folder. Build paths from __dirname instead:

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));

It printed config.json dark and index.js. The full paths differ on every machine, which is exactly why you build them with path.join(__dirname, ...) rather than typing them.

__dirname in ES modules: import.meta.dirname

ES modules have no __dirname; using it throws ReferenceError: __dirname is not defined in ES module scope. Since Node.js 20.11, import.meta.dirname and import.meta.filename replace them:

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));

It printed index.js and data/users.json. On Node.js versions before 20.11, derive the folder from the module URL: path.dirname(fileURLToPath(import.meta.url)), with fileURLToPath from node:url.

Why not join paths with strings

'data' + '/' + file works on macOS and Linux, then fails on Windows, where the separator is \, and it does nothing about .., doubled slashes or a missing slash. path uses the rules of the system it runs on. You can see the Windows result from any machine with 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

Pass the result of path.join to fs.readFile and the same code reads the file on every system.

Common mistakes

Expecting extname to know about double extensions. path.extname('archive.tar.gz') is '.gz', and a dotfile such as .env has no extension at all: path.extname('.env') is ''. Check the end of the name yourself when the full suffix matters.

Trusting join to keep a user inside a folder. path.join('/srv/app', '../../etc/passwd') is '/etc/passwd'. Before you read a file named by a request, resolve the path and check that it still starts with your folder.