upath

Version 3 introduces several improvements:

• Full TypeScript Support: The package is rewritten in TypeScript with full type safety and source-of-truth types. It is compatible with @types/node v20 through v25+.
• Dual CJS/ESM Support: Works with both import and require() via package.json exports.
• UNC Path Support: Comprehensive support for UNC paths is included.
• Auto-generated API Docs: Complete input/output tables are available in the repository's docs/API.md.

upath acts as a thin dynamic proxy over Node's built-in path module. It iterates over every export of path and wraps functions so that:

1. String arguments are normalized (converting \ to /) on the way in.
2. String results are normalized on the way out.
3. Non-function properties are copied as-is, except sep, which is forced to '/'.

Because it uses a proxy, any new functions added to Node's path module in future releases are automatically wrapped and available in upath without requiring an update to the upath package itself.

Install upath via npm to use it as a drop-in replacement for Node.js path that normalizes all backslashes to forward slashes across all platforms.

npm install upath

You can import the entire library or specific functions using ESM or CommonJS syntax.

// ESM
import upath from 'upath'
// or import specific functions
import { normalize, joinSafe, addExt } from 'upath'

// CJS
const upath = require('upath')

When upgrading from version 2 to version 3, note the following breaking changes and requirements:

• Node.js Requirement: You must use Node.js version 20 or higher.
• TypeScript Strictness: The parameters for join(), resolve(), and joinSafe() have been narrowed from any[] to string[]. If you are passing variables that are not explicitly typed as strings, you must use explicit casts (e.g., join(myVar as string)).
• Removed Function: _makeLong has been removed. Use toNamespacedPath instead.
• String Types: Boxed String objects (e.g., new String('foo')) are no longer accepted. Use plain string primitives.
• ESM Imports: You can now use named ESM imports: import { normalize, join, toUnix } from 'upath'.
• CJS Usage: CommonJS usage remains unchanged. const upath = require('upath') works without needing .default.

The upath library provides a drop-in replacement for the Node.js path module. It automatically converts all backslashes to forward slashes and collapses duplicate slashes (while preserving leading double-slashes for UNC paths). This ensures consistent Unix-style path handling regardless of the host operating system. The upath.sep is always '/'.

import upath from 'upath';

// Standard Node.js path functions are available and automatically unix-ified
const joined = upath.join('foo', 'bar', 'baz'); // 'foo/bar/baz'
const resolved = upath.resolve('foo', 'bar'); // 'current/working/dir/foo/bar'

// The full object is available as a default export
console.log(upath.VERSION);

The upath.isAbsolute(path) function determines if a path is absolute. Notably, upath performs backslash normalization during this check, meaning paths using backslashes (common in Windows environments) are correctly identified as absolute if they follow absolute path patterns.

// Examples of backslash normalization in isAbsolute
upath.isAbsolute("\\foo") // true
upath.isAbsolute("\\\\server\\share") // true
upath.isAbsolute("foo\\bar") // false

Use upath.toUnix(path) to convert all backslashes to forward slashes and consolidate duplicate slashes without performing full path normalization.

upath.toUnix('.//windows\//unix//mixed////') // './windows/unix/mixed/'
upath.toUnix('\\server\share') // '//server/share'
upath.toUnix('C:\Users\test') // 'C:/Users/test'

Removes a specific extension from a filename if it matches the provided ext parameter. If the extension does not match, the filename is returned unchanged.

// Removes exact extension
upath.removeExt("removedExt.js", '.js'); // "removedExt"

// Removes extension from end of chain
upath.removeExt("removedExt.txt.js", '.js'); // "removedExt.txt"

// No change if extension doesn't match
upath.removeExt("notRemoved.txt", '.js'); // "notRemoved.txt"

Converts a path to use forward slashes (/) exclusively, regardless of the input format (Windows or Unix). It also collapses multiple consecutive slashes into a single slash (except for the leading // in UNC paths).

// Converts backslashes to forward slashes
upath.toUnix("a\\b\\c"); // "a/b/c"

// Collapses multiple slashes
upath.toUnix("////multiple///slashes"); // "//multiple/slashes"

// Handles Windows drive letters
upath.toUnix("C:\\Users\\test"); // "C:/Users/test"

// Preserves UNC prefix
upath.toUnix("\\\\server\\share"); // "//server/share"

A safer version of Node.js path.normalize. It resolves .. and . segments and collapses multiple slashes, but crucially preserves leading ./ and // (for UNC/network paths). It also converts Windows-style UNC paths (e.g., \\server\share) to Unix-style forward slash paths (//server/share).

// Preserves leading ./
upath.normalizeSafe("./dep"); // "./dep"

// Preserves leading // (UNC paths)
upath.normalizeSafe("\\\\server\\share\\file"); // "//server/share/file"

// Resolves segments while preserving prefix
upath.normalizeSafe("./path/../dep"); // "./dep"