npm-run

<script>
    The name of the script to execute as defined in the "scripts" section of package.json.

-- <args>...
    Used to pass additional arguments directly to the executed script. Everything after -- is treated as arguments for the script itself, not for npm run.

--silent or -s
    Suppresses output from npm itself, showing only the standard output and error of the executed script.

--if-present
    Prevents npm run from throwing an error if the specified script does not exist in package.json. The command will simply exit with status 0.

--workspace <workspace_name> or -w <workspace_name>
    Executes the script within a specific workspace (for monorepos). Can be specified multiple times to target multiple workspaces.

--prefix <path>
    Sets the directory where npm run will look for the package.json file to read scripts from. Useful for running scripts in a different project root.

The npm run command is a fundamental utility within the Node.js ecosystem, primarily used to execute arbitrary commands defined in the "scripts" field of a project's package.json file.

It serves as the backbone for automating various development tasks, including building projects, running tests, linting code, starting development servers, and deploying applications. When npm run executes a script, it automatically prepends the node_modules/.bin directory to the system's PATH, making locally installed executable packages available directly by name without needing to specify their full path.

Scripts are executed in a sub-shell, allowing for the use of shell-specific features like pipes, redirects, and environment variables. If additional arguments need to be passed to the executed script, they can be appended after a "--" separator. Running npm run without any arguments will list all available scripts defined in the package.json. It's an indispensable tool for managing project workflows and ensuring consistent task execution across different development environments.

When running scripts, npm run temporarily modifies the system's PATH environment variable to include node_modules/.bin. This allows direct execution of binaries installed by local dependencies. Scripts are executed in a sub-shell, which means platform-specific shell syntax (e.g., Windows vs. Linux/macOS commands, path separators, variable expansion) must be considered for cross-platform compatibility. The exit code of the script executed by npm run is propagated as the exit code of the npm run command itself. Always be cautious when running scripts from untrusted package.json files, as they can execute arbitrary commands on your system.

npm run automatically executes special lifecycle scripts defined as pre<script> and post<script> before and after the main script, respectively. For example, running npm run test will first execute a pretest script (if defined), then the test script, and finally the posttest script.

Inside a script executed by npm run, numerous environment variables are made available, providing context about the project, npm configuration, and the currently running script. These include variables like NPM_PACKAGE_NAME, NPM_PACKAGE_VERSION, NPM_CONFIG_PREFIX, and NPM_COMMAND, among others, prefixed with NPM_.

For commonly used scripts, npm provides convenient shortcuts. Commands like npm start, npm test, npm stop, and npm restart are direct aliases for npm run start, npm run test, npm run stop, and npm run restart, respectively. This simplifies their invocation.

Script execution has been a core feature of the Node Package Manager (npm) since its early days, making it an integral part of the Node.js development workflow. The full command, npm run-script, was later aliased to the more convenient and widely used npm run for brevity. Its evolution has closely mirrored the growth of the Node.js and JavaScript ecosystems, adapting to new project structures like monorepos with features like workspace support, and remaining a central tool for task automation.

npm install(1), npm start(1), npm test(1), npm stop(1), npm restart(1), package.json(5)