npm-run-script

View documentation for the original command

$ tldr npm run

npm run <script-name> [-- <args>...]
npm run [<script-name>]
(Man page name: npm-run-script)

<script-name>
    The name of the script defined in the scripts section of package.json. If omitted, npm run will list all available scripts.

-- <args>...
    A special separator that indicates all subsequent arguments should be passed directly to the executed script, rather than being interpreted by npm itself.

--silent, -s
    Suppresses output from npm itself (e.g., info messages, progress bars), showing only the standard output and error of the executed script.

--if-present
    If the specified script is not found in package.json, npm run will exit without an error. If the script is found, it behaves normally.

--ignore-scripts
    Prevents the execution of pre- and post-lifecycle scripts that would normally run in conjunction with the specified script.

--workspace <name>, -w <name>
    Run the script within a specific npm workspace by its name.

--workspaces, -ws
    Run the script in all configured workspaces within the current project.

The npm run command (documented as npm-run-script) is a fundamental utility within the npm ecosystem for executing arbitrary commands defined in a project's package.json file. It allows developers to automate common tasks such as building, testing, starting development servers, linting, and more. When executed, npm run searches for a script with the specified name in the scripts object of the current package.json. If found, it executes the corresponding command in a subshell (e.g., sh on Unix-like systems, cmd.exe on Windows).

A key feature of npm run is its automatic modification of the PATH environment variable to include the node_modules/.bin directory. This means that local executables (like webpack, eslint, jest, etc.) installed as development dependencies can be run directly by their name without needing to specify their full path. Beyond user-defined scripts, npm run also handles special lifecycle scripts (like preinstall, postinstall, pretest, postbuild), ensuring that certain actions are performed before or after other npm commands or custom scripts.

Scripts executed by npm run are run in a subshell. This means that their behavior can differ slightly depending on the operating system and the specific shell environment (e.g., bash or zsh on Unix-like systems versus cmd.exe or PowerShell on Windows). Users should be aware of these shell-specific nuances, especially when writing cross-platform scripts.

It's crucial to exercise caution when running scripts from untrusted or unknown sources, as they have the capability to execute arbitrary commands on your system, potentially leading to security vulnerabilities or unintended system modifications.

For any script named <script-name>, npm will automatically run a pre<script-name> script before it and a post<script-name> script after it (if defined in package.json). For example, npm run build would trigger prebuild, then build, then postbuild. This mechanism provides hooks for preparatory and cleanup tasks.

Certain script names have special significance or aliases: start (can be run directly as npm start), test (npm test), stop (npm stop), and restart (npm restart). These commands are essentially shortcuts for npm run <script-name>. Additionally, if a start script is not defined, npm start defaults to running node server.js.

When a script is executed, npm populates the environment with various variables. These include npm_package_<field> (e.g., npm_package_name, npm_package_version, derived from package.json fields), and ensures that the node_modules/.bin directory is added to the PATH, allowing local binaries to be run directly by name without a full path.

The exit code of npm run is typically the exit code of the executed script. If the script fails (exits with a non-zero code), npm run will also exit with that non-zero code, making it suitable for use in continuous integration (CI) environments or shell scripting for error handling.

The npm run-script functionality, commonly accessed via npm run, has been a core and foundational feature of npm since its early versions, establishing npm as a robust task runner for Node.js projects. It quickly became the de facto standard for defining and executing project-specific commands, offering a simpler, built-in alternative to more complex external build systems or Makefiles. Its integration with package.json streamlined project setup and task automation, allowing developers to define and share common workflows directly within their project's metadata. Over the years, while the core functionality remained consistent, npm run has evolved to support modern development patterns, notably with the introduction of npm workspaces, enhancing its capability for managing scripts across monorepos and complex project structures.

npm(1), npm-scripts(7), npm-start(1), npm-test(1), npm-stop(1), npm-restart(1), package.json(5)