0
# npm-run-path
1

2
Get your PATH prepended with locally installed binaries. This utility provides the same PATH augmentation that npm run scripts use internally, enabling execution of locally installed binaries by name outside of npm run scripts.
3

4
## Package Information
5

6
- **Package Name**: npm-run-path
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install npm-run-path`
10

11
## Core Imports
12

13
```typescript
14
import { npmRunPath, npmRunPathEnv, type ProcessEnv, type RunPathOptions, type EnvOptions } from 'npm-run-path';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { npmRunPath, npmRunPathEnv } = require('npm-run-path');
21
```
22

23
## Basic Usage
24

25
```typescript
26
import childProcess from 'node:child_process';
27
import { npmRunPath, npmRunPathEnv } from 'npm-run-path';
28

29
console.log(process.env.PATH);
30
//=> '/usr/local/bin'
31

32
console.log(npmRunPath());
33
//=> '/Users/sindresorhus/dev/foo/node_modules/.bin:/Users/sindresorhus/dev/node_modules/.bin:/Users/sindresorhus/node_modules/.bin:/Users/node_modules/.bin:/node_modules/.bin:/usr/local/bin'
34

35
// Execute locally installed binary using augmented PATH string
36
childProcess.exec('eslint --version', { env: { ...process.env, PATH: npmRunPath() } });
37

38
// Or use the environment object directly
39
childProcess.execFileSync('eslint', ['--version'], {
40
  env: npmRunPathEnv()
41
});
42
```
43

44
## Capabilities
45

46
### PATH String Generation
47

48
Generate an augmented PATH string with locally installed binaries prepended.
49

50
```typescript { .api }
51
export function npmRunPath(options?: RunPathOptions): string;
52
```
53

54
**Usage Example:**
55

56
```typescript
57
import { npmRunPath } from 'npm-run-path';
58

59
// Default behavior - current directory, include local binaries
60
const path = npmRunPath();
61

62
// Custom working directory
63
const customPath = npmRunPath({ cwd: '/path/to/project' });
64

65
// Exclude locally installed binaries
66
const globalOnlyPath = npmRunPath({ preferLocal: false });
67

68
// Custom PATH to append (instead of process.env.PATH)
69
const customBasePath = npmRunPath({ path: '/usr/bin:/bin' });
70

71
// Exclude Node.js executable directory
72
const noExecPath = npmRunPath({ addExecPath: false });
73
```
74

75
### Environment Object Generation
76

77
Generate an augmented environment object with modified PATH.
78

79
```typescript { .api }
80
export function npmRunPathEnv(options?: EnvOptions): ProcessEnv;
81
```
82

83
**Usage Example:**
84

85
```typescript
86
import childProcess from 'node:child_process';
87
import { npmRunPathEnv } from 'npm-run-path';
88

89
// Use with child_process
90
childProcess.execFileSync('eslint', ['--version'], {
91
  env: npmRunPathEnv()
92
});
93

94
// Custom environment base
95
const customEnv = npmRunPathEnv({
96
  env: { NODE_ENV: 'production', PATH: '/custom/path' }
97
});
98

99
// Custom working directory
100
const projectEnv = npmRunPathEnv({ cwd: '/path/to/project' });
101
```
102

103
## Types
104

105
```typescript { .api }
106
type CommonOptions = {
107
	/**
108
	Working directory.
109

110
	@default process.cwd()
111
	*/
112
	readonly cwd?: string | URL;
113

114
	/**
115
	The path to the current Node.js executable.
116

117
	This can be either an absolute path or a path relative to the `cwd` option.
118

119
	@default [process.execPath](https://nodejs.org/api/process.html#processexecpath)
120
	*/
121
	readonly execPath?: string | URL;
122

123
	/**
124
	Whether to push the current Node.js executable's directory (`execPath` option) to the front of PATH.
125

126
	@default true
127
	*/
128
	readonly addExecPath?: boolean;
129

130
	/**
131
	Whether to push the locally installed binaries' directory to the front of PATH.
132

133
	@default true
134
	*/
135
	readonly preferLocal?: boolean;
136
};
137

138
export type RunPathOptions = CommonOptions & {
139
	/**
140
	PATH to be appended.
141

142
	Set it to an empty string to exclude the default PATH.
143

144
	@default [`PATH`](https://github.com/sindresorhus/path-key)
145
	*/
146
	readonly path?: string;
147
};
148

149
export type ProcessEnv = Record<string, string | undefined>;
150

151
export type EnvOptions = CommonOptions & {
152
	/**
153
	Accepts an object of environment variables, like `process.env`, and modifies the PATH using the correct [PATH key](https://github.com/sindresorhus/path-key). Use this if you're modifying the PATH for use in the `child_process` options.
154

155
	@default [process.env](https://nodejs.org/api/process.html#processenv)
156
	*/
157
	readonly env?: ProcessEnv;
158
};
159
```
160

161
## How It Works
162

163
The package automatically discovers and prepends `node_modules/.bin` directories by:
164

165
1. Starting from the current working directory (or specified `cwd`)
166
2. Adding `node_modules/.bin` to the PATH
167
3. Moving up one directory level and repeating until reaching the filesystem root
168
4. Optionally adding the Node.js executable's directory to the PATH
169
5. Appending the original PATH (or specified `path`)
170

171
This creates a PATH that prioritizes locally installed binaries over global ones, matching npm run script behavior.
172

173
## Common Use Cases
174

175
- **CLI Tools**: Enable CLI tools to execute locally installed binaries
176
- **Build Scripts**: Use in build systems that need to run project-specific tools
177
- **Child Processes**: Spawn processes with access to local binaries
178
- **Development Tools**: Allow development tools to use project-specific versions of utilities