path — Paths

Working with file and directory paths in Node.js — join, resolve, extname, dirname, basename, and cross-platform path handling.

What it is, in plain English: The path module provides utilities for working with file paths. It handles the difference between Unix forward slashes and Windows backslashes automatically. path.join() safely concatenates path segments. path.resolve() converts a relative path to an absolute one. path.extname(), path.basename(), and path.dirname() extract parts of a path. Always use path.join() instead of string concatenation for file paths.

Where this bites you

A Windows path pasted into a normal JavaScript string loses its backslashes, because \ starts an escape sequence. "C:\Users\nina\temp" becomes C:Users, a newline, ina, a tab and emp. \n and \t are real escapes, and \U just drops the backslash. No error is raised. path.join can't help, because the damage is done before it ever sees the string.

import { win32 } from "path";

const folder = "C:\Users\nina\temp";           // copied straight from Explorer
console.log(win32.join(folder, "report.txt"));
console.log(JSON.stringify(folder));           // what the string really contains
// C:Users
// ina	emp\report.txt
// "C:Users\nina\temp"

Working with file paths safely

File paths look like strings — and beginners often treat them as strings. This causes bugs on Windows (which uses backslashes) or when segments are accidentally doubled ("dir//file"). The path module handles all of this.

Import

import { join, resolve, basename, dirname, extname, parse } from "path";

path.join — the most important function

// Always use path.join() to combine path segments:
console.log(join("src", "utils", "helpers.js"));  // "src/utils/helpers.js"
console.log(join("/home", "alice", "docs"));       // "/home/alice/docs"

// Handles extra slashes gracefully:
console.log(join("src/", "/utils/", "file.js"));  // "src/utils/file.js"

// On Windows, path.join uses backslashes automatically:
// join("C:\\Users", "alice", "file.txt")  → C:\Users\alice\file.txt

// ✗ DON'T concatenate paths manually:
const bad  = "src/" + "utils/" + "file.js";   // fragile
const good = join("src", "utils", "file.js"); // safe everywhere

When you have to write a Windows path in source code, double every backslash, or use String.raw, which takes the text exactly as written. Better still, avoid hard-coded absolute paths and build them with join() from pieces such as os.homedir(), which works on every platform:

import { win32 } from "path";

const folder  = "C:\\Users\\nina\\temp";       // every backslash doubled
const folder2 = String.raw`C:\Users\nina\temp`; // or: a raw template string, no escapes
console.log(win32.join(folder, "report.txt"));
console.log(folder === folder2);
// C:\Users\nina\temp\report.txt
// true

path.basename, dirname, extname

const filePath = "/home/alice/projects/app.js";

console.log(basename(filePath));         // "app.js"
console.log(basename(filePath, ".js"));  // "app" (strip extension)
console.log(dirname(filePath));          // "/home/alice/projects"
console.log(extname(filePath));          // ".js"

// Useful patterns:
const ext  = extname(filePath).slice(1);  // "js" (without the dot)
const name = basename(filePath, extname(filePath));  // "app"

path.resolve — relative to absolute

// resolve() works from the current working directory:
// (assuming process.cwd() = "/home/alice/projects")
console.log(resolve("src/app.js"));          // "/home/alice/projects/src/app.js"
console.log(resolve("../other/file.txt"));   // "/home/alice/other/file.txt"
console.log(resolve("/etc/config.json"));    // "/etc/config.json" (absolute, unchanged)

// Chain multiple segments:
console.log(resolve("dist", "assets", "img")); // "/home/alice/projects/dist/assets/img"

Getting __dirname in ES modules

// In CommonJS, __dirname is built-in.
// In ES modules (.mjs / "type":"module"), use import.meta.url:
import { fileURLToPath } from "url";
import { dirname, join }  from "path";

const __filename = fileURLToPath(import.meta.url);  // current file path
const __dirname  = dirname(__filename);              // current directory

// Now use __dirname exactly like you would in CJS:
const configPath = join(__dirname, "config.json");
const distDir    = join(__dirname, "..", "dist");

Try It Yourself

// path module — file path utilities
// Simulated in browser (real module is Node.js only)

// Simplified path implementations for demo:
const path = {
  join:      (...parts) => parts.join("/").replace(/\/+/g, "/"),
  basename:  (p, ext) => {
    const base = p.split("/").pop() || p.split("\\").pop();
    return ext && base.endsWith(ext) ? base.slice(0, -ext.length) : base;
  },
  dirname:   (p) => p.split("/").slice(0, -1).join("/") || ".",
  extname:   (p) => { const base = p.split("/").pop(); const dot = base.lastIndexOf("."); return dot < 1 ? "" : base.slice(dot); },
  resolve:   (...parts) => "/" + parts.join("/").replace(/\/+/g, "/"),
  isAbsolute: (p) => p.startsWith("/") || /^[A-Za-z]:/.test(p),
  parse:     (p) => {
    const ext  = p.slice(p.lastIndexOf("."));
    const base = p.split("/").pop();
    const name = base.slice(0, -ext.length);
    const dir  = p.slice(0, p.lastIndexOf("/"));
    return { root: "/", dir, base, ext, name };
  },
};

// path.join — safely combine path segments (handles slashes):
console.log(path.join("src", "utils", "helpers.js"));  // "src/utils/helpers.js"
console.log(path.join("/home", "alice", "docs"));       // "/home/alice/docs"
// DON'T do: "src/" + "utils/" + "file.js"  ← brittle
// DO: path.join("src", "utils", "file.js")

// path.basename — get filename from path:
console.log(path.basename("/home/alice/report.pdf"));       // "report.pdf"
console.log(path.basename("/home/alice/report.pdf", ".pdf")); // "report" (strip ext)

// path.dirname — get directory:
console.log(path.dirname("/home/alice/report.pdf")); // "/home/alice"
console.log(path.dirname("src/utils/helpers.js"));   // "src/utils"

// path.extname — get extension:
console.log(path.extname("photo.jpg"));      // ".jpg"
console.log(path.extname("archive.tar.gz")); // ".gz" (only last extension)
console.log(path.extname("README"));         // "" (no extension)

// path.parse — decompose a path:
const parsed = path.parse("/home/alice/report.pdf");
console.log(parsed);
// { root: "/", dir: "/home/alice", base: "report.pdf", ext: ".pdf", name: "report" }

// path.isAbsolute:
console.log(path.isAbsolute("/home/alice"));   // true
console.log(path.isAbsolute("./relative"));    // false

path.parse, path.format, and cross-platform patterns

// path.parse — decompose a path into all its parts:
const { root, dir, base, name, ext } = parse("/home/alice/report.2024.pdf");
// root: "/"
// dir:  "/home/alice"
// base: "report.2024.pdf"
// name: "report.2024"
// ext:  ".pdf"

// path.format — reverse of parse:
import { format } from "path";
const newPath = format({ dir: "/home/alice", name: "report-v2", ext: ".pdf" });
// "/home/alice/report-v2.pdf"

// Change a file's extension:
function changeExt(filePath, newExt) {
  const { dir, name } = parse(filePath);
  return format({ dir, name, ext: newExt });
}
changeExt("style.scss", ".css");  // "style.css"

// path.relative — relative path from A to B:
import { relative } from "path";
relative("/home/alice/src", "/home/alice/dist/app.js");  // "../dist/app.js"

// path.normalize — clean up messy paths:
import { normalize } from "path";
normalize("/home//alice/../alice/docs/./readme.md");  // "/home/alice/docs/readme.md"

Cross-platform path handling

// path.posix — always use forward slashes (for URLs, POSIX systems):
import { posix } from "path";
posix.join("src", "utils", "file.js");  // "src/utils/file.js"

// path.win32 — always use backslashes (for Windows paths):
import { win32 } from "path";
win32.join("C:\\Users", "alice", "file.txt");  // C:\Users\alice\file.txt

// Convert a file path to a URL:
import { pathToFileURL, fileURLToPath } from "url";
const url = pathToFileURL("/home/alice/app.js");
// URL { href: "file:///home/alice/app.js", pathname: "/home/alice/app.js" }
const backToPath = fileURLToPath(url.href);  // "/home/alice/app.js"

Path spec, SEP, and delimiter

import { sep, delimiter, posix, win32 } from "path";

// sep — the platform's path separator:
console.log(sep);  // "/" on POSIX, "\" on Windows

// delimiter — the platform's PATH env var separator:
console.log(delimiter);  // ":" on POSIX, ";" on Windows
console.log(process.env.PATH.split(delimiter));  // list of directories in PATH

// path.toNamespacedPath (Windows only) — extended-length path prefix:
// Converts "C:\very\long\path" to "\\?\C:\very\long\path"
// Needed for paths longer than MAX_PATH (260 chars) on Windows

// The path module is entirely synchronous — no I/O.
// It performs pure string operations using platform-specific separators.
// path.posix and path.win32 allow cross-platform path manipulation
// regardless of the current OS (useful in build tools, CLI tools).

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.