{"id":15290285,"url":"https://github.com/npm/run-script","last_synced_at":"2025-04-14T05:16:31.434Z","repository":{"id":37650343,"uuid":"235679249","full_name":"npm/run-script","owner":"npm","description":"Run a lifecycle script for a package (descendant of npm-lifecycle)","archived":false,"fork":false,"pushed_at":"2025-04-01T15:48:51.000Z","size":579,"stargazers_count":58,"open_issues_count":1,"forks_count":23,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-04-14T05:16:29.688Z","etag":null,"topics":["npm-cli"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/npm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-01-22T22:21:24.000Z","updated_at":"2025-04-04T04:28:40.000Z","dependencies_parsed_at":"2023-01-26T11:31:57.682Z","dependency_job_id":"f95dcbda-a922-400d-845f-4a9e91debca4","html_url":"https://github.com/npm/run-script","commit_stats":{"total_commits":239,"total_committers":18,"mean_commits":"13.277777777777779","dds":0.7740585774058577,"last_synced_commit":"a8b4034bf91e348b73426400baa9caf040f3b8ea"},"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Frun-script","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Frun-script/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Frun-script/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/npm%2Frun-script/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/npm","download_url":"https://codeload.github.com/npm/run-script/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248824693,"owners_count":21167345,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["npm-cli"],"created_at":"2024-09-30T16:06:47.019Z","updated_at":"2025-04-14T05:16:31.362Z","avatar_url":"https://github.com/npm.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @npmcli/run-script\n\nRun a lifecycle script for a package (descendant of npm-lifecycle)\n\n## USAGE\n\n```js\nconst runScript = require('@npmcli/run-script')\n\nrunScript({\n  // required, the script to run\n  event: 'install',\n\n  // extra args to pass to the command, defaults to []\n  args: [],\n\n  // required, the folder where the package lives\n  path: '/path/to/package/folder',\n\n  // optional, these paths will be put at the beginning of `$PATH`, even\n  // after run-script adds the node_modules/.bin folder(s) from\n  // `process.cwd()`. This is for commands like `npm init`, `npm exec`,\n  // and `npx` to make sure manually installed  packages come before\n  // anything that happens to be in the tree in `process.cwd()`.\n  binPaths: [\n    '/path/to/npx/node_modules/.bin',\n    '/path/to/npm/prefix/node_modules/.bin',\n  ],\n\n  // optional, defaults to /bin/sh on unix, or cmd.exe on windows\n  scriptShell: '/bin/bash',\n\n  // optional, passed directly to `@npmcli/promise-spawn` which defaults it to true\n  // return stdout and stderr as strings rather than buffers\n  stdioString: false,\n\n  // optional, additional environment variables to add\n  // note that process.env IS inherited by default\n  // Always set:\n  // - npm_package_json The package.json file in the folder\n  // - npm_lifecycle_event The event that this is being run for\n  // - npm_lifecycle_script The script being run\n  // The fields described in https://github.com/npm/rfcs/pull/183\n  env: {\n    npm_package_from: 'foo@bar',\n    npm_package_resolved: 'https://registry.npmjs.org/foo/-/foo-1.2.3.tgz',\n    npm_package_integrity: 'sha512-foobarbaz',\n  },\n\n  // defaults to 'pipe'.  Can also pass an array like you would to node's\n  // exec or spawn functions.  Note that if it's anything other than\n  // 'pipe' then the stdout/stderr values on the result will be missing.\n  // npm cli sets this to 'inherit' for explicit run-scripts (test, etc.)\n  // but leaves it as 'pipe' for install scripts that run in parallel.\n  stdio: 'inherit',\n\n  // print the package id and script, and the command to be run, like:\n  // \u003e somepackage@1.2.3 postinstall\n  // \u003e make all-the-things\n})\n  .then(({ code, signal, stdout, stderr, pkgid, path, event, script }) =\u003e {\n    // do something with the results\n  })\n  .catch(er =\u003e {\n    // command did not work.\n    // er is decorated with:\n    // - code\n    // - signal\n    // - stdout\n    // - stderr\n    // - path\n    // - pkgid (name@version string)\n    // - event\n    // - script\n  })\n```\n\n## API\n\nCall the exported `runScript` function with an options object.\n\nReturns a promise that resolves to the result of the execution.  Promise\nrejects if the execution fails (exits non-zero) or has any other error.\nRejected errors are decorated with the same values as the result object.\n\nIf the stdio options mean that it'll have a piped stdin, then the stdin is\nended immediately on the child process.  If stdin is shared with the parent\nterminal, then it is up to the user to end it, of course.\n\n### Results\n\n- `code` Process exit code\n- `signal` Process exit signal\n- `stdout` stdout data (Buffer, or String when `stdioString` set to true)\n- `stderr` stderr data (Buffer, or String when `stdioString` set to true)\n- `path` Path to the package executing its script\n- `event` Lifecycle event being run\n- `script` Command being run\n\nIf stdio is `inherit` this package will emit a banner with the package\nname and version, event name, and script command to be run, and send it\nto [`proc-log.output.standard`](https://npm.im/proc-log).  Consuming\nlibraries can decide whether or not to display this.\n\n### Options\n\n- `path` Required.  The path to the package having its script run.\n- `event` Required.  The event being executed.\n- `args` Optional, default `[]`.  Extra arguments to pass to the script.\n- `env` Optional, object of fields to add to the environment of the\n  subprocess.  Note that process.env IS inherited by default These are\n  always set:\n  - `npm_package_json` The package.json file in the folder\n  - `npm_lifecycle_event` The event that this is being run for\n  - `npm_lifecycle_script` The script being run\n  - The `package.json` fields described in\n    [RFC183](https://github.com/npm/rfcs/pull/183/files).\n- `scriptShell` Optional, defaults to `/bin/sh` on Unix, defaults to\n  `env.ComSpec` or `cmd` on Windows.  Custom script to use to execute the\n  command.\n- `stdio` Optional, defaults to `'pipe'`.  The same as the `stdio` argument\n  passed to `child_process` functions in Node.js.  Note that if a stdio\n  output is set to anything other than `pipe`, it will not be present in\n  the result/error object.\n- `cmd` Optional.  Override the script from the `package.json` with\n  something else, which will be run in an otherwise matching environment.\n- `stdioString` Optional, passed directly to `@npmcli/promise-spawn` which\n  defaults it to `true`.  Return string values for `stderr` and `stdout` rather\n  than Buffers.\n\nNote that this does _not_ run pre-event and post-event scripts.  The\ncaller has to manage that process themselves.\n\n## Differences from [npm-lifecycle](https://github.com/npm/npm-lifecycle)\n\nThis is an implementation to satisfy [RFC\n90](https://github.com/npm/rfcs/pull/90), [RFC\n77](https://github.com/npm/rfcs/pull/77), and [RFC\n73](https://github.com/npm/rfcs/pull/73).\n\nApart from those behavior changes in npm v7, this is also just refresh of\nthe codebase, with modern coding techniques and better test coverage.\n\nFunctionally, this means:\n\n- Output is not dumped to the top level process's stdio by default.\n- Less stuff is put into the environment.\n- It is not opinionated about logging.  (So, at least with the logging\n  framework in npm v7.0 and before, the caller has to call\n  `log.disableProgress()` and `log.enableProgress()` at the appropriate\n  times, if necessary.)\n- The directory containing the `node` executable is _never_ added to the\n  `PATH` environment variable.  (Ie, `--scripts-prepend-node-path` is\n  effectively always set to `false`.)  Doing so causes more unintended side\n  effects than it ever prevented.\n- Hook scripts are not run by this module.  If the caller wishes to run\n  hook scripts, then they can override the default package script with an\n  explicit `cmd` option pointing to the `node_modules/.hook/${event}`\n  script.\n\n## Escaping\n\nIn order to ensure that arguments are handled consistently, this module\nwrites a temporary script file containing the command as it exists in\nthe package.json, followed by the user supplied arguments having been\nescaped to ensure they are processed as literal strings. We then instruct\nthe shell to execute the script file, and when the process exits we remove\nthe temporary file.\n\nIn Windows, when the shell is cmd, and when the initial command in the script\nis a known batch file (i.e. `something.cmd`) we double escape additional\narguments so that the shim scripts npm installs work correctly.\n\nThe actual implementation of the escaping is in `lib/escape.js`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpm%2Frun-script","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnpm%2Frun-script","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnpm%2Frun-script/lists"}