# @nodewell/path

> A Node.js utility to provide a simple solution for path management in your build scripts and in general tasks.

Latest version **1.1.4** (published 2020-04-28) · ISC license · 0 weekly downloads

## Install

```sh
npm install @nodewell/path
pnpm add @nodewell/path
yarn add @nodewell/path
bun add @nodewell/path
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.4 |
| Published | 2020-04-28 |
| First published | 2020-03-28 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=8 |
| Dependencies | 3 |
| Unpacked size | 17.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Richard King |
| Maintainers | richrdkng |
| Keywords | node, nodewell, path, paths |

## Links

- npm: https://www.npmjs.com/package/@nodewell/path
- Repository: https://github.com/nodewell/path
- Homepage: https://github.com/nodewell/path#readme
- Issues: https://github.com/nodewell/path/issues
- npm.io page: https://npm.io/package/@nodewell/path

## Dependencies (3)

- [yaml](https://npm.io/package/yaml.md) ^1.9.0
- [pkg-dir](https://npm.io/package/pkg-dir.md) ^4.2.0
- [string-similarity](https://npm.io/package/string-similarity.md) ^4.0.1

## Alternatives

- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads

## Recent versions

- 1.1.4 (latest) — 2020-04-28
- 1.1.3 — 2020-04-19
- 1.1.2 — 2020-04-17
- 1.1.1 — 2020-04-17
- 1.1.0 — 2020-04-01
- 1.0.1 — 2020-03-28
- 1.0.0 — 2020-03-28

## README

<!-- Logo -->
<p align="center">
  <img width="250" src="https://cdn.jsdelivr.net/gh/nodewell/path/assets/icon-with-name-color.svg" alt="@nodewell/path" />
</p>

<!-- Branded divider -->
<a href="https://github.com/nodewell"><img src="https://cdn.jsdelivr.net/npm/@nodewell/assets@1.2.1/media/github/divider.svg" alt="divider" /></a>

<!-- Badges - 1st row -->
<p align="center">
  <!-- NPM badge -->
  <a href="https://www.npmjs.com/package/@nodewell/path"><img src="https://img.shields.io/npm/v/@nodewell/path?color=brightgreen&style=flat-square" alt="release-badge"></a>
  <!-- CI badge -->
  <a href="https://github.com/nodewell/path/actions?query=workflow%3Aci"><img src="https://github.com/nodewell/path/workflows/ci/badge.svg?style=flat-square" alt="ci-badge"></a>
  <!-- Coverage badge -->
  <a href="https://codecov.io/gh/nodewell/path"><img src="https://img.shields.io/codecov/c/github/nodewell/path?style=flat-square" alt="coverage-badge"></a>
  <!-- Dependency badge -->
  <a href="https://libraries.io/github/nodewell/path"><img src="https://img.shields.io/badge/dependabot-enabled-brightgreen.svg?style=flat-square" alt="dependency-badge"></a>
  <!-- Documentation badge -->
  <a href="https://github.com/nodewell/path/blob/master/doc/API.md"><img src="https://inch-ci.org/github/nodewell/path.svg?branch=master&style=flat-square" alt="documentation-badge"></a>
</p>

<!-- Badges - 2nd row -->
<p align="center">
  <!-- Code style badge -->
  <a href="https://standardjs.com"><img src="https://img.shields.io/badge/style-standardjs-f1d300.svg?style=flat-square" alt="code-style-badge"></a>
  <!-- Commit style badge -->
  <a href="https://commitizen.github.io/cz-cli"><img src="https://img.shields.io/badge/commit-commitizen-fe7d37.svg?style=flat-square" alt="commit-style-badge"></a>
  <!-- Release workflow badge -->
  <a href="https://semantic-release.gitbook.io/semantic-release"><img src="https://img.shields.io/badge/release-semantic--release-e10079.svg?style=flat-square" alt="release-workflow-badge"></a>
  <!-- License badge -->
  <a href="https://github.com/nodewell/path/blob/master/LICENSE.md"><img src="https://img.shields.io/badge/license-ISC-blue.svg?style=flat-square" alt="license-badge"></a>
  <!-- Contribution badge -->
  <a href="https://github.com/nodewell/path/blob/master/.github/CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" alt="contribution-badge"></a>
</p>

---

<h3 align="center">
  Painless, simple, easy path management.
</h3>

<p align="center">
  A Node.js utility to provide a simple solution for path management
  in your build scripts and in general tasks.
</p>

---

## :thinking: Why?

- **Before:** :thumbsdown:

  ```javascript
  // project_root/scripts/build/frontend.js
  const path = require('path')

  const root = path.join(__dirname, '../../')
  const dist = path.join(root, '/frontend/dist')
  const src = path.join(root, '/frontend/src')
  // ...
  ```

- **After:** :thumbsup:

  ```javascript
  // /project_root/scripts/build/frontend.js
  const path = require('@nodewell/path')

  path('@') // '/project_root'
  path('@/frontend/dist') // '/project_root/frontend/dist'
  path('@/frontend/src') // '/project_root/frontend/src'
  // ...
  ```

- **Even Better:** :ok_hand:

  Use a `.pathrc` file with your custom paths in your project's root:

  ```json
  {
    "@dist": "./frontend/dist",
    "@src": "./frontend/src",
    "@custom-path": "@/custom/path"
  }
  ```

  ...then, when you use **`@nodewell/path`**, your paths will be available in the whole project / package:

  ```javascript
  const path = require('@nodewell/path')

  path('@dist') // '/project_root/frontend/dist'
  path('@src') // '/project_root/frontend/src'
  path('@custom-path') // '/project_root/custom/path'
  ```

## :package: Installation

- **NPM:**

  ```bash
  npm install @nodewell/path
  ```

- **Yarn:**

  ```bash
  yarn add @nodewell/path
  ```

## :coffee: Usage

**`@nodewell/path`** is intended to be used **with Node.js** primarily.

```javascript
const path = require('@nodewell/path')
```

After **`@nodewell/path`** is loaded, it **determines your project's root automatically**
based on the directory, where your **`package.json`** can be found.

```javascript
// assuming your project's package.json can be found in '/home/user/project/package.json'

// access your project's root directory
path('@') // '/home/user/project'

// access a file in your project
path('@/src/index.js') // '/home/user/project/src/index.js'

// access a directory in your project
path('@/src') // '/home/user/project/src'

// access files and directories
path('@/src/**/*.js') // '/home/user/project/src/**/*.js'
path('@/test/') // '/home/user/project/test/'
path('@/test/fixtures') // '/home/user/project/test/fixtures'

// access files with the '***' (triple-dot) glob
path('@/src/***') // '/home/user/project/src/**/*.*'
```

To define **custom, project-wide paths**, use a `.pathrc` file with your own custom paths:

```json
{
  "@dist": "./dist",
  "@src": "./src",
  "@custom-path": "@/custom/path"
}
```

Supported `.pathrc` file names:

 - JSON formats:
   - `.pathrc`
   - `.pathsrc`
   - `.path.json`
   - `.paths.json`

 - JavaScript (Node.js CommonJS module) formats:
   - `.path.config.js`
   - `.paths.config.js`
 
 - YAML formats:
   - `.path.yml`
   - `.paths.yml`
   - `.path.yaml`
   - `.paths.yaml`

---

## :computer: API

<!--- <% api --->
<a name="module_@nodewell/path"></a>

## @nodewell/path
<a name="exp_module_@nodewell/path--module.exports"></a>

### module.exports(paths) ⇒ <code>string</code> ⏏
Processes and returns the path segments.

**Returns**: <code>string</code> - Returns the processed path segments.  
<table>
  <thead>
    <tr>
      <th>Param</th><th>Type</th><th>Description</th>
    </tr>
  </thead>
  <tbody>
<tr>
    <td>paths</td><td><code>string</code> | <code>Array.&lt;string&gt;</code></td><td><p>The path segments to process.</p>
</td>
    </tr>  </tbody>
</table>

**Example**  
```js
// assuming your project's root is '/home/user/project'
const path = require('@nodewell/path')

path('@') // '/home/user/project'
path('@/src') // '/home/user/project/src'
path('@/src/*.js') // '/home/user/project/src/*.js'
```
<!--- api %> --->

---

## :star: Related

Check out the [official website][url-website] for more tools, utilities, and packages.

Find more **@nodewell** packages on [NPM][url-npm] and [GitHub][url-github].

## :beers: Contribution

**Any contribution is ***highly*** appreciated**. To get going, check out the [**contribution guidelines**][url-contrib-doc].

***Thank you and have fun!***

## :copyright: License

[ISC][url-license-doc] @ [Richard King](https://www.richrdkng.com)

  <!--- References ============================================================================ -->

  <!--- URLs -->
  [url-website]:     https://nodewell.github.io
  [url-github]:      https://github.com/nodewell
  [url-npm]:         https://www.npmjs.com/search?q=keywords:nodewell
  [url-contrib-doc]: https://github.com/nodewell/path/blob/master/.github/CONTRIBUTING.md
  [url-license-doc]: https://github.com/nodewell/path/blob/master/LICENSE.md

---
_Source: https://npm.io/package/@nodewell/path · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._