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.

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

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.