Bare Path Manipulation

3.0.0 · active · verified Sun Apr 19

bare-path is a JavaScript library designed for cross-platform path manipulation, focusing on string-based operations rather than interacting with the underlying file system. It provides utilities for joining, normalizing, resolving, and dissecting file paths, similar to Node.js's built-in `path` module. The current stable version is 3.0.0. Its primary differentiator is its minimalist approach and explicit separation of POSIX and Windows path logic via subpath exports, making it highly portable and suitable for environments where `node:path` might not be available or desired due to its implicit OS-specific behavior. It maintains a steady release cadence for core utility packages, prioritizing stability and broad compatibility.

Common errors

```
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'bare-path' imported from ...
```
cause Attempting to import `bare-path` in an ES module context using a CommonJS `require()` syntax, or incorrect `package.json` `type` field setting.

fix If using ES modules, ensure you are using `import path from 'bare-path';`. If in a CommonJS context, use `const path = require('bare-path');`. Verify that your `package.json` has `"type": "module"` if you intend to use ESM globally, or manage file extensions (`.mjs`/`.cjs`).
```
Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]: Only URLs with a scheme in: file, data, and node are supported by the default ESM loader. On Windows, absolutePath is something like C:\Users\...\node_modules\...\index.js.
```
cause Dynamic `import()` on Windows with a bare, absolute path (e.g., `C:\path\to\module.js`) instead of a `file://` URL scheme. This is a Node.js ESM loader requirement.

fix Before dynamically importing a local absolute path on Windows, convert it to a `file://` URL: `import { pathToFileURL } from 'node:url'; const modulePath = pathToFileURL(absolutePath).href; await import(modulePath);`

Warnings

breaking Version 3.x introduces explicit ES Modules (`'exports'` field in `package.json`) which might alter module resolution behavior, especially for subpath imports and CJS interoperability. Direct access to internal files via deep `require()` or `import` paths might be broken.
Fix: Migrate to standard ES module imports (e.g., `import path from 'bare-path'`) and use the official subpath exports (`bare-path/win32`, `bare-path/posix`) for platform-specific utilities. Ensure your `package.json` specifies `"type": "module"` for ESM usage or correctly configures a CJS environment.
gotcha `bare-path` is purely a string manipulation utility and does not interact with the file system. It will not resolve symbolic links, check for file existence, or convert paths to absolute paths relative to the current working directory on disk. This differs from aspects of `node:path` module when used with `fs` operations.
Fix: Understand that `bare-path` operates solely on the provided string inputs. For file system interactions (e.g., `fs.readFile`), use `node:path` methods if you need guarantees about actual file system paths, or manually combine `bare-path` outputs with `process.cwd()` for root-relative paths.
gotcha When using `bare-path` on Windows, ensure you are aware of path separator differences. While `path.join` and `path.normalize` abstract this, manually constructed paths or external inputs may use backslashes (`\`) which might require explicit handling or using the `bare-path/win32` export for Windows-specific behaviors.
Fix: Prefer `path.join()`, `path.resolve()`, and `path.normalize()` methods for cross-platform compatibility. If you need strict platform behavior, explicitly import and use `bare-path/posix` or `bare-path/win32`.

Install

npm install bare-path npm
yarn add bare-path yarn
pnpm add bare-path pnpm

Imports

path
wrong:
```
import { path } from 'bare-path';
```
correct:
```
import path from 'bare-path';
```
The main path utilities object is exported as a default. For full CommonJS interoperability in ESM, use `import * as path from 'bare-path';`.
path (CommonJS)
wrong:
```
const { path } = require('bare-path');
```
correct:
```
const path = require('bare-path');
```
CommonJS `require` imports the entire module object, which is the path utility methods.
win32Path
wrong:
```
import { win32Path } from 'bare-path';
```
correct:
```
import win32Path from 'bare-path/win32';
```
Access platform-specific path utilities directly via subpath imports. Similar import for `bare-path/posix` exists.

Quickstart

Demonstrates basic path manipulation functions like joining, normalizing, and extracting parts of a path using `bare-path`.

import path from 'bare-path';

// Join path segments, handling separators automatically
const fullPath = path.join('users', 'admin', 'documents', 'report.txt');
console.log(`Joined path: ${fullPath}`); // Expected: users/admin/documents/report.txt (on POSIX)

// Normalize a path, resolving '..' and '.' segments
const normalizedPath = path.normalize('/foo/bar//../baz/.');
console.log(`Normalized path: ${normalizedPath}`); // Expected: /foo/baz

// Get the directory name of a path
const dirname = path.dirname('/home/user/file.js');
console.log(`Directory name: ${dirname}`); // Expected: /home/user

// Get the base name of a path (filename)
const basename = path.basename('/home/user/file.js');
console.log(`Base name: ${basename}`); // Expected: file.js

// Get the base name without extension
const basenameNoExt = path.basename('/home/user/file.js', '.js');
console.log(`Base name without extension: ${basenameNoExt}`); // Expected: file

// Get the extension of a path
const extname = path.extname('/home/user/archive.tar.gz');
console.log(`Extension name: ${extname}`); // Expected: .gz

view raw JSON →