File Paths

The path module provides utilities for working with file and directory paths.

When working with file systems and handling file paths dynamically, correctly manipulating and resolving file paths will ensure your program works correctly on any operating system.

// A naive implementation of path joining that works for many common cases
function join(...parts: string[]) {
    return parts.map((part) => part.replace(/(^\/|\/$)/g, '')).join('/')
}
console.log(join('/foo/', 'bar/baz/', '/quux'))
console.log(join('https://example.com/', '/user/request'))
// Doesn't work - should be /my/other_folder
console.log(join('/my/directory', '../other_folder'))

Joining paths

The path.join function correctly joins path segments.

import path from 'path'
console.log(path.join('/no/more/', '/slash/worries'))
console.log(path.join('welcome', 'to/this', 'tutorial', '../lesson'))

Note that path.join should not be used with URLs that contain a protocol like https://.

import path from 'path'
// Notice the "https://" is "https:/" in the output
console.log(path.join('https://example.com/', '/user/requested'))

Parsing a path

The path.parse function produces an object with useful information about the path.

import path from 'path'
console.log(path.parse('/foo/bar/baz'))
console.log(path.parse('/foo/bar/quux.html'))

Formatting a path

An object like the one produced by path.parse can be converted back into a correctly formatted path with path.format.

import path from 'path'
console.log(path.format({
    root: '/',
    dir: '/foo/bar',
    base: 'quux.html',
    ext: '.html',
    name: 'quux'
}))

Note that if you are using this function to change some particular information about the path - for example, the file extension - you need to update both ext and base. Consider the example below, which computes the path to a compiled .js file corresponding to an original Typescript .ts file.

import path from 'path'
// Parse the path to an example TypeScript file
const tsFile = '/vm/sandbox/app.ts'
const parsed = path.parse(tsFile)
// incorrect, since path.base is still "app.ts"
parsed.ext = '.js'
console.log(path.format(parsed))
// now correct
parsed.base = path.basename(parsed.base, '.ts') + '.js'
console.log(path.format(parsed))

Joining paths

Joins all given path segments into a single normalized path.

import path from 'path'
const desktop = '/Users/tscoach/Desktop'
console.log(path.join(desktop, 'website', 'files'))
console.log(path.join(desktop, '../Music'))
console.log(path.join(desktop, '../..'))
console.log(path.join(desktop, '..'))
console.log(path.join(desktop, '.'))

Zero-length path segments are ignored, which allows you to safely use a string to serve as a path modifier. You cannot use null or undefined as a path segment for path.join.

import path from 'path'
console.log(path.join('a', 'b', 'c'))
console.log(path.join('a', '', 'c'))

Base name

import path from 'path'
console.log(path.basename('C:\\temp\\myfile.html'))

The path separator can vary based on operating system, namely for Windows and POSIX systems. To ensure consistent results, use path.win32 when working with Windows file paths, and path.posix when working with POSIX file paths.

// On POSIX
path.basename('C:\\temp\\myfile.html')       // "C:\\temp\\myfile.html"
path.posix.basename('C:\\temp\\myfile.html') // "myfile.html"
// On Windows
path.basename('C:\\temp\\myfile.html')       // "myfile.html"
path.win32.basename('C:\\temp\\myfile.html') // "myfile.html"

Directory name

Returns the parent directory for the given path.

import path from 'path'
console.log(path.dirname('/Users/tscoach/index.html'))
// Works the same with trailing slashes
console.log(path.dirname('/a/b/c'))
console.log(path.dirname('/a/b/'))
console.log(path.dirname('/a/b'))

Platform constants

There are two platform-specific constants - sep and delimiter. The platform-specific path segment separator in sep is \ on Windows and / on POSIX, and the delimiter is ; on Windows and : on POSIX.

import path from 'path'
// Showing UNIX output
console.log(path.sep)
console.log(path.delimiter)

These values are commonly used in split operations that should be platform-independent.

// On POSIX/Mac
console.log(process.env.PATH)           
// POSIX:   '/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin'
// Windows: 'C:\Windows\system32;C:\Windows;C:\Program Files\node\'
process.env.PATH.split(path.delimiter)
// POSIX:   ['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin']
// Windows: ['C:\\Windows\\system32', 'C:\\Windows', 'C:\\Program Files\\node\\']