Repository files navigation

Run a lifecycle script for a package (descendant of npm-lifecycle)

construnScript=require('@npmcli/run-script')runScript({// required, the script to runevent:'install',// extra args to pass to the command, defaults to []args:[],// required, the folder where the package livespath:'/path/to/package/folder',// optional, these paths will be put at the beginning of `$PATH`, even// after run-script adds the node_modules/.bin folder(s) from// `process.cwd()`. This is for commands like `npm init`, `npm exec`,// and `npx` to make sure manually installed  packages come before// anything that happens to be in the tree in `process.cwd()`.binPaths:['/path/to/npx/node_modules/.bin','/path/to/npm/prefix/node_modules/.bin',],// optional, defaults to /bin/sh on unix, or cmd.exe on windowsscriptShell:'/bin/bash',// optional, passed directly to `@npmcli/promise-spawn` which defaults it to true// return stdout and stderr as strings rather than buffersstdioString:false,// optional, additional environment variables to add// note that process.env IS inherited by default// Always set:// - npm_package_json The package.json file in the folder// - npm_lifecycle_event The event that this is being run for// - npm_lifecycle_script The script being run// The fields described in https://github.com/npm/rfcs/pull/183env:{npm_package_from:'foo@bar',npm_package_resolved:'https://registry.npmjs.org/foo/-/foo-1.2.3.tgz',npm_package_integrity:'sha512-foobarbaz',},// defaults to 'pipe'.  Can also pass an array like you would to node's// exec or spawn functions.  Note that if it's anything other than// 'pipe' then the stdout/stderr values on the result will be missing.// npm cli sets this to 'inherit' for explicit run-scripts (test, etc.)// but leaves it as 'pipe' for install scripts that run in parallel.stdio:'inherit',// print the package id and script, and the command to be run, like:// > somepackage@1.2.3 postinstall// > make all-the-things}).then(({ code, signal, stdout, stderr, pkgid, path, event, script})=>{// do something with the results}).catch(er=>{// command did not work.// er is decorated with:// - code// - signal// - stdout// - stderr// - path// - pkgid (name@version string)// - event// - script})

Call the exportedrunScript function with an options object.

Returns a promise that resolves to the result of the execution. Promiserejects if the execution fails (exits non-zero) or has any other error.Rejected errors are decorated with the same values as the result object.

If the stdio options mean that it'll have a piped stdin, then the stdin isended immediately on the child process. If stdin is shared with the parentterminal, then it is up to the user to end it, of course.

• code Process exit code
• signal Process exit signal
• stdout stdout data (Buffer, or String whenstdioString set to true)
• stderr stderr data (Buffer, or String whenstdioString set to true)
• path Path to the package executing its script
• event Lifecycle event being run
• script Command being run

If stdio isinherit this package will emit a banner with the packagename and version, event name, and script command to be run, and send ittoproc-log.output.standard. Consuminglibraries can decide whether or not to display this.

• path Required. The path to the package having its script run.
• event Required. The event being executed.
• args Optional, default[]. Extra arguments to pass to the script.
• env Optional, object of fields to add to the environment of thesubprocess. Note that process.env IS inherited by default These arealways set:
  • npm_package_json The package.json file in the folder
  • npm_lifecycle_event The event that this is being run for
  • npm_lifecycle_script The script being run
  • Thepackage.json fields described inRFC183.
• scriptShell Optional, defaults to/bin/sh on Unix, defaults toenv.ComSpec orcmd on Windows. Custom script to use to execute thecommand.
• stdio Optional, defaults to'pipe'. The same as thestdio argumentpassed tochild_process functions in Node.js. Note that if a stdiooutput is set to anything other thanpipe, it will not be present inthe result/error object.
• cmd Optional. Override the script from thepackage.json withsomething else, which will be run in an otherwise matching environment.
• stdioString Optional, passed directly to@npmcli/promise-spawn whichdefaults it totrue. Return string values forstderr andstdout ratherthan Buffers.

Note that this doesnot run pre-event and post-event scripts. Thecaller has to manage that process themselves.

This is an implementation to satisfyRFC90,RFC77, andRFC73.

Apart from those behavior changes in npm v7, this is also just refresh ofthe codebase, with modern coding techniques and better test coverage.

Functionally, this means:

• Output is not dumped to the top level process's stdio by default.
• Less stuff is put into the environment.
• It is not opinionated about logging. (So, at least with the loggingframework in npm v7.0 and before, the caller has to calllog.disableProgress() andlog.enableProgress() at the appropriatetimes, if necessary.)
• The directory containing thenode executable isnever added to thePATH environment variable. (Ie,--scripts-prepend-node-path iseffectively always set tofalse.) Doing so causes more unintended sideeffects than it ever prevented.
• Hook scripts are not run by this module. If the caller wishes to runhook scripts, then they can override the default package script with anexplicitcmd option pointing to thenode_modules/.hook/${event}script.

In order to ensure that arguments are handled consistently, this modulewrites a temporary script file containing the command as it exists inthe package.json, followed by the user supplied arguments having beenescaped to ensure they are processed as literal strings. We then instructthe shell to execute the script file, and when the process exits we removethe temporary file.

In Windows, when the shell is cmd, and when the initial command in the scriptis a known batch file (i.e.something.cmd) we double escape additionalarguments so that the shim scripts npm installs work correctly.

The actual implementation of the escaping is inlib/escape.js.