https://github.com/wessberg/crosspath
A wrapper around the path module that always normalizes to POSIX (including converting backslashes to forward slashes)
https://github.com/wessberg/crosspath
cross-platform module node normalize path util
Last synced: 7 months ago
JSON representation
A wrapper around the path module that always normalizes to POSIX (including converting backslashes to forward slashes)
- Host: GitHub
- URL: https://github.com/wessberg/crosspath
- Owner: wessberg
- License: mit
- Created: 2021-05-26T14:58:48.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2022-05-30T11:48:25.000Z (over 3 years ago)
- Last Synced: 2025-05-27T07:18:19.131Z (8 months ago)
- Topics: cross-platform, module, node, normalize, path, util
- Language: TypeScript
- Homepage:
- Size: 411 KB
- Stars: 3
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
> A wrapper around the path module that always normalizes to POSIX (including converting backslashes to forward slashes)
## Description
The built-in [`path` module](https://nodejs.org/api/path.html) in Node.js provides utilities for working with file and directory paths in Node.js. The default operation
of it varies [based on the operating system](https://nodejs.org/api/path.html#path_windows_vs_posix) on which Node.js is running.
While this is generally a good thing, there are situations where you might want to normalize paths such that they always follow POSIX formatting.
While the `path` module _does_ export POSIX specific implementations via the [`path.posix`](https://nodejs.org/api/path.html#path_path_posix) property,
it is not really sufficient, as it doesn't convert windows-style paths with backslashes into forward slashes.
`crosspath` is a drop-in replacement for `path` that wraps it to ensure that paths are always POSIX-formatted, including on Windows.
You can still access the underlying implementations via the `native` property, which is useful when you do need to convert back into OS-specific
paths, for example when writing to the file system
### Features
- A drop-in replacement
- Tiny as it relies on the implementations of the underlying path module
## Backers
| 
| 
| 
| 
| 
| 
|
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| [Bubbles](https://usebubbles.com)
Twitter: [@usebubbles](https://twitter.com/usebubbles) | [Christopher Blanchard](https://github.com/cblanc) | [Ideal Postcodes](https://github.com/ideal-postcodes) | [Xerox](https://www.xerox.com) | [Trent Raymond](https://changelog.me) | [scrubtheweb](https://scrubtheweb.com) |
### Patreon
## Table of Contents
- [Description](#description)
- [Features](#features)
- [Backers](#backers)
- [Patreon](#patreon)
- [Table of Contents](#table-of-contents)
- [Install](#install)
- [npm](#npm)
- [Yarn](#yarn)
- [pnpm](#pnpm)
- [Usage](#usage)
- [Contributing](#contributing)
- [Maintainers](#maintainers)
- [FAQ](#faq)
- [Why not simply use `path.posix` always? Isn't this library redundant?](#why-not-simply-use-pathposix-always-isnt-this-library-redundant)
- [License](#license)
## Install
### npm
```
$ npm install crosspath
```
### Yarn
```
$ yarn add crosspath
```
### pnpm
```
$ pnpm add crosspath
```
## Usage
Simply import what you need, exactly as you would with the `path` module:
```ts
// Import just what you need:
import {join, relative} from "crosspath";
// or simply:
import path from "crosspath";
// Becomes 'C:/foo/bar'
path.join("C:\\foo", "\\bar");
// Becomes '../bar'
path.relative("C:\\foo", "C:\\bar");
```
If you want to use the native path helpers and constants without the POSIX normalization, these are all accessible
via the `path.native` property:
```ts
import path from "crosspath";
// Becomes 'C:\foo\bar' on Windows and C:\foo/\bar on POSIX-systems
path.native.join("C:\\foo", "\\bar");
// Becomes '..\bar' on Windows and ../C:\bar on POSIX-systems
path.native.relative("C:\\foo", "C:\\bar");
```
This can be useful when you _do_ want the paths to respect the OS convention, such as when you interact with the file system.
## Contributing
Do you want to contribute? Awesome! Please follow [these recommendations](./CONTRIBUTING.md).
## Maintainers
| 
|
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Frederik Wessberg](mailto:frederikwessberg@hotmail.com)
Twitter: [@FredWessberg](https://twitter.com/FredWessberg)
Github: [@wessberg](https://github.com/wessberg)
_Lead Developer_ |
## FAQ
### Why not simply use `path.posix` always? Isn't this library redundant?
No, not quite (but close). While it is true that `path.posix` can be used from Windows, it has the fundamental
shortcoming that it [doesn't convert backslashes into forward slashes](https://nodejs.org/api/path.html#path_path_normalize_path).
This is not a mistake, but rather a design decision. This library makes another decision and unifies the behavior between
the two approaches to make it easier to build cross-platform libraries and tools.
## License
MIT © [Frederik Wessberg](mailto:frederikwessberg@hotmail.com) ([@FredWessberg](https://twitter.com/FredWessberg)) ([Website](https://github.com/wessberg))