npm-run-path vs npx: when to use which?

Use npm-run-path when you need fine-grained control over the environment in custom scripts or build tools, as it integrates directly with child_process. npx is better for one-off CLI commands or when you prefer a simpler, no-code approach.

How to use npm-run-path with async child processes?

Pass the environment object from npmRunPathEnv() to the env option of child_process.spawn or execFile. Handle promises or callbacks as per Node.js async patterns, ensuring the modified PATH is used during execution.

Does npm-run-path work with monorepos?

Yes, by setting the cwd option to the appropriate subdirectory, it can include binaries from nested node_modules directories, following npm's resolution logic that walks up the directory tree.

Can I use npm-run-path in a Docker container?

Absolutely, it's useful in Docker to ensure local binaries are available in the container's PATH. Install it as a dependency and invoke it in your entrypoint or build scripts to replicate local development behavior.

How to handle PATH conflicts with npm-run-path?

Use the preferLocal and addExecPath options to control the order of directories. If issues persist, inspect the returned PATH string or adjust the path option to manually resolve conflicts.

Is npm-run-path compatible with TypeScript?

Yes, it includes built-in TypeScript definitions, so you can import it directly in TypeScript projects without needing additional @types packages, as confirmed by the ES module import syntax in the README.

Open-Awesome

npm-run-path

MITJavaScriptv6.0.0

Get your PATH prepended with locally installed binaries, enabling npm-like script execution outside npm.

GitHub

109 stars10 forks0 contributors

What is npm-run-path?

npm-run-path is a Node.js library that modifies the system PATH to include locally installed npm package binaries. It solves the problem of executing locally installed command-line tools outside of npm run scripts, making them accessible as if they were globally installed. This ensures consistent behavior across different execution contexts in Node.js projects.

Target Audience

Node.js developers and tooling authors who need to execute locally installed binaries from scripts, build tools, or child processes outside the npm run-script environment.

Value Proposition

Developers choose npm-run-path because it provides a reliable, cross-platform way to replicate npm's binary resolution behavior, eliminating the need for manual PATH manipulation or global installations. Its tight integration with Node's child_process module and flexible configuration make it a robust utility for build tools and development workflows.

Overview

Get your PATH prepended with locally installed binaries

Use Cases

Best For

Executing locally installed CLI tools from custom Node.js scripts
Building development tools that need to run project-specific binaries
Creating cross-platform build scripts that depend on local dependencies
Integrating with child_process methods like execFile or spawn
Ensuring consistent binary resolution in testing environments
Developing npm-like script runners or task automation tools

Not Ideal For

Projects using Yarn or pnpm as the primary package manager without npm compatibility
Simple Node.js scripts that only need to run globally installed binaries
Environments with strict security policies that prohibit dynamic PATH modification

Pros & Cons

Pros

Predictable Binary Prioritization

Ensures locally installed npm binaries are found first by prepending node_modules/.bin directories to PATH, as shown in the usage example where 'foo' is executed without a full path.

Child Process Integration

Provides npmRunPathEnv() to return a full environment object, making it seamless to use with child_process.execFileSync and similar methods for spawning processes.

Configurable Execution Context

Supports options like cwd and execPath to customize the working directory and Node.js executable path, offering flexibility for complex or nested project structures.

Cross-Platform Reliability

Handles OS-specific environment variable keys (e.g., PATH vs. Path) correctly, ensuring consistent behavior on Windows, macOS, and Linux without manual adjustments.

Cons

Tied to NPM Ecosystem

Designed specifically for npm-run scripts; does not natively support binaries from other package managers like Yarn or pnpm, limiting its use in polyglot or modern monorepo setups.

Adds Library Dependency

Introduces an external dependency for PATH manipulation, which could be overkill for trivial cases where simple PATH updates or using npx might suffice.

No Built-in Execution Wrapper

Only modifies the PATH; actual binary execution and error handling must be implemented separately using child_process methods, adding boilerplate code compared to integrated tools.

Frequently Asked Questions

Related Projects

npm-check

Check for outdated, incorrect, and unused dependencies.

Stars6,637

Forks235

Last commit6 days ago

npm-run-all

A CLI tool to run multiple npm-scripts in parallel or sequential.

Stars5,839

Forks239

Last commit1 year ago

npm-windows-upgrade

:rocket: Upgrade npm on Windows

Stars2,507

Forks145

Last commit5 years ago

emma-cli

📦 Terminal assistant to find and install node packages.

Stars1,245

Forks42

Last commit8 days ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub