Node.js Path Module Guide

The path module provides utilities for working with file paths. Here's how to use it effectively.

Basic Path Operations#

const path = require('path');

// Join path segments
const fullPath = path.join('users', 'alice', 'documents', 'file.txt');
// 'users/alice/documents/file.txt' (Unix)
// 'users\\alice\\documents\\file.txt' (Windows)

// Resolve to absolute path
const absolute = path.resolve('src', 'components', 'Button.tsx');
// '/current/working/dir/src/components/Button.tsx'

// Get directory name
const dir = path.dirname('/users/alice/documents/file.txt');
// '/users/alice/documents'

// Get file name
const file = path.basename('/users/alice/documents/file.txt');
// 'file.txt'

// Get file name without extension
const name = path.basename('/users/alice/documents/file.txt', '.txt');
// 'file'

// Get file extension
const ext = path.extname('/users/alice/documents/file.txt');
// '.txt'

Path Parsing and Formatting#

const path = require('path');

// Parse path into components
const parsed = path.parse('/home/user/documents/report.pdf');
// {
//   root: '/',
//   dir: '/home/user/documents',
//   base: 'report.pdf',
//   ext: '.pdf',
//   name: 'report'
// }

// Windows path
const winParsed = path.win32.parse('C:\\Users\\Alice\\file.txt');
// {
//   root: 'C:\\',
//   dir: 'C:\\Users\\Alice',
//   base: 'file.txt',
//   ext: '.txt',
//   name: 'file'
// }

// Format path from components
const formatted = path.format({
  root: '/',
  dir: '/home/user',
  base: 'file.txt',
});
// '/home/user/file.txt'

// Partial format
const partial = path.format({
  dir: '/home/user',
  name: 'document',
  ext: '.pdf',
});
// '/home/user/document.pdf'

Relative and Absolute Paths#

const path = require('path');

// Check if path is absolute
path.isAbsolute('/foo/bar'); // true
path.isAbsolute('./foo/bar'); // false
path.isAbsolute('foo/bar'); // false

// Windows
path.win32.isAbsolute('C:\\foo'); // true
path.win32.isAbsolute('\\foo'); // true
path.win32.isAbsolute('foo'); // false

// Get relative path between two paths
const from = '/data/users/alice';
const to = '/data/posts/123/content.md';
const relative = path.relative(from, to);
// '../../posts/123/content.md'

// Resolve relative to specific directory
const resolved = path.resolve('/home/user', './documents', '../downloads');
// '/home/user/downloads'

Path Normalization#

const path = require('path');

// Normalize path (resolve . and ..)
path.normalize('/foo/bar//baz/asdf/quux/..');
// '/foo/bar/baz/asdf'

path.normalize('C:\\temp\\\\foo\\bar\\..\\');
// 'C:\\temp\\foo\\'

// Remove trailing slashes
function removeTrailingSlash(p) {
  return p.replace(/[\\/]+$/, '');
}

// Ensure trailing slash
function ensureTrailingSlash(p) {
  return p.endsWith(path.sep) ? p : p + path.sep;
}

// Clean path
function cleanPath(p) {
  return path.normalize(p).replace(/[\\/]+$/, '');
}

Cross-Platform Handling#

const path = require('path');

// Platform-specific separator
console.log(path.sep);
// '/' on Unix, '\\' on Windows

// Platform-specific delimiter (for PATH)
console.log(path.delimiter);
// ':' on Unix, ';' on Windows

// Force Unix paths
const unixPath = path.posix.join('users', 'alice', 'file.txt');
// 'users/alice/file.txt' (always)

// Force Windows paths
const winPath = path.win32.join('users', 'alice', 'file.txt');
// 'users\\alice\\file.txt' (always)

// Convert Windows paths to Unix
function toUnixPath(p) {
  return p.split(path.sep).join('/');
}

// Convert Unix paths to Windows
function toWindowsPath(p) {
  return p.split('/').join('\\');
}

// Platform-independent comparison
function pathsEqual(p1, p2) {
  return path.resolve(p1) === path.resolve(p2);
}

Common Patterns#

const path = require('path');

// Get project root
const projectRoot = path.resolve(__dirname, '..');

// Build file paths
function getFilePath(filename) {
  return path.join(projectRoot, 'data', filename);
}

// Change extension
function changeExtension(file, newExt) {
  const { dir, name } = path.parse(file);
  return path.join(dir, `${name}${newExt}`);
}

changeExtension('/path/to/file.txt', '.md');
// '/path/to/file.md'

// Add suffix before extension
function addSuffix(file, suffix) {
  const { dir, name, ext } = path.parse(file);
  return path.join(dir, `${name}${suffix}${ext}`);
}

addSuffix('/path/to/file.txt', '.min');
// '/path/to/file.min.txt'

// Get unique filename
function uniqueFilename(file) {
  const { dir, name, ext } = path.parse(file);
  const timestamp = Date.now();
  return path.join(dir, `${name}-${timestamp}${ext}`);
}

Working with dirname and filename#

// CommonJS
const path = require('path');

console.log(__dirname); // Directory of current file
console.log(__filename); // Full path of current file

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

// ES Modules (no __dirname)
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

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

// Helper for ES Modules
function getDirname(importMetaUrl) {
  return dirname(fileURLToPath(importMetaUrl));
}

const dir = getDirname(import.meta.url);

Path Validation#

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

// Check if path is within directory (prevent traversal)
function isWithinDirectory(child, parent) {
  const relative = path.relative(parent, child);
  return relative && !relative.startsWith('..') && !path.isAbsolute(relative);
}

// Usage for security
function safeReadFile(basePath, userPath) {
  const fullPath = path.resolve(basePath, userPath);

  if (!isWithinDirectory(fullPath, basePath)) {
    throw new Error('Access denied: path traversal detected');
  }

  return fs.readFileSync(fullPath, 'utf-8');
}

// Validate filename
function isValidFilename(filename) {
  // No path separators
  if (filename.includes('/') || filename.includes('\\')) {
    return false;
  }
  // No special characters
  const invalid = /[<>:"|?*\x00-\x1f]/;
  return !invalid.test(filename);
}

// Sanitize filename
function sanitizeFilename(filename) {
  return filename
    .replace(/[<>:"|?*\x00-\x1f]/g, '')
    .replace(/[\\/]/g, '-')
    .trim();
}

URL and Path Conversion#

const path = require('path');
const { URL, pathToFileURL, fileURLToPath } = require('url');

// Path to file URL
const fileUrl = pathToFileURL('/home/user/file.txt');
// file:///home/user/file.txt

// File URL to path
const filePath = fileURLToPath('file:///home/user/file.txt');
// '/home/user/file.txt'

// URL path segment
const url = new URL('https://example.com/path/to/file.txt');
const urlPath = url.pathname;
// '/path/to/file.txt'

// Join URL paths
function joinUrlPath(...segments) {
  return segments
    .map(s => s.replace(/^\/+|\/+$/g, ''))
    .filter(Boolean)
    .join('/');
}

joinUrlPath('/api/', '/users/', '/123');
// 'api/users/123'

Glob Pattern Helpers#

const path = require('path');

// Match file extension
function matchesExtension(file, extensions) {
  const ext = path.extname(file).toLowerCase();
  return extensions.includes(ext);
}

// Get files matching pattern (basic)
function getMatchingFiles(dir, pattern) {
  const files = fs.readdirSync(dir);

  if (pattern.startsWith('*.')) {
    const ext = pattern.slice(1);
    return files.filter(f => f.endsWith(ext));
  }

  return files.filter(f => f.includes(pattern.replace('*', '')));
}

// Build glob pattern
function buildGlob(dir, extensions) {
  const extPattern = extensions.length === 1
    ? extensions[0]
    : `{${extensions.join(',')}}`;

  return path.join(dir, '**', `*${extPattern}`);
}

buildGlob('src', ['.ts', '.tsx']);
// 'src/**/*.{ts,tsx}'

Best Practices#

Cross-Platform:
✓ Always use path.join() for paths
✓ Use path.sep for separators
✓ Avoid hardcoded slashes
✓ Test on both platforms

Security:
✓ Validate paths from user input
✓ Use isWithinDirectory checks
✓ Sanitize filenames
✓ Resolve before validation

Patterns:
✓ Use path.resolve() for absolute paths
✓ Use path.parse() for components
✓ Store __dirname in ES Modules
✓ Normalize before comparing

Avoid:
✗ String concatenation for paths
✗ Assuming path separator
✗ Trusting user-provided paths
✗ Using relative paths without resolve

The path module is essential for cross-platform file operations. Use path.join() and path.resolve() instead of string concatenation, validate user input to prevent path traversal, and use path.parse() for extracting components. Always consider cross-platform compatibility in your path handling code.