---

Painless, simple, easy path management.

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

---

🤔 Why?

• Before: 👎

  // 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: 👍

  // /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: 👌

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

  {
    "@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:

  const path = require('@nodewell/path')
  
  path('@dist') // '/project_root/frontend/dist'
  path('@src') // '/project_root/frontend/src'
  path('@custom-path') // '/project_root/custom/path'

📦 Installation

• NPM:

  npm install @nodewell/path

• Yarn:

  yarn add @nodewell/path

☕ Usage

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

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.

// 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:

{
  "@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

---

💻 API

@nodewell/path

module.exports(paths) ⇒ string ⏏

Processes and returns the path segments.

Returns: string - Returns the processed path segments.

Param	Type	Description
paths	string | Array.<string>	The path segments to process.

Example

// 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'

---

⭐ Related

Check out the official website for more tools, utilities, and packages.

Find more @nodewell packages on NPM and GitHub.

🍻 Contribution

Any contribution is highly appreciated. To get going, check out the contribution guidelines.

Thank you and have fun!

©️ License

ISC @ Richard King