:thinking: Why?

• Before: :thumbsdown:

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

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

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

:package: Installation

• NPM:

  npm install @nodewell/path

• Yarn:

  yarn add @nodewell/path

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

:computer: API