1--- 2title: npm-run-script 3section: 1 4description: Run arbitrary package scripts 5--- 6 7### Synopsis 8 9```bash 10npm run-script <command> [-- <args>] 11 12aliases: run, rum, urn 13``` 14 15### Description 16 17This runs an arbitrary command from a package's `"scripts"` object. If no 18`"command"` is provided, it will list the available scripts. 19 20`run[-script]` is used by the test, start, restart, and stop commands, but 21can be called directly, as well. When the scripts in the package are 22printed out, they're separated into lifecycle (test, start, restart) and 23directly-run scripts. 24 25Any positional arguments are passed to the specified script. Use `--` to 26pass `-`-prefixed flags and options which would otherwise be parsed by npm. 27 28For example: 29 30```bash 31npm run test -- --grep="pattern" 32``` 33 34The arguments will only be passed to the script specified after `npm run` 35and not to any `pre` or `post` script. 36 37The `env` script is a special built-in command that can be used to list 38environment variables that will be available to the script at runtime. If an 39"env" command is defined in your package, it will take precedence over the 40built-in. 41 42In addition to the shell's pre-existing `PATH`, `npm run` adds 43`node_modules/.bin` to the `PATH` provided to scripts. Any binaries 44provided by locally-installed dependencies can be used without the 45`node_modules/.bin` prefix. For example, if there is a `devDependency` on 46`tap` in your package, you should write: 47 48```bash 49"scripts": {"test": "tap test/*.js"} 50``` 51 52instead of 53 54```bash 55"scripts": {"test": "node_modules/.bin/tap test/*.js"} 56``` 57 58The actual shell your script is run within is platform dependent. By default, 59on Unix-like systems it is the `/bin/sh` command, on Windows it is 60`cmd.exe`. 61The actual shell referred to by `/bin/sh` also depends on the system. 62You can customize the shell with the 63[`script-shell` config](/using-npm/config#script-shell). 64 65Scripts are run from the root of the package folder, regardless of what the 66current working directory is when `npm run` is called. If you want your 67script to use different behavior based on what subdirectory you're in, you 68can use the `INIT_CWD` environment variable, which holds the full path you 69were in when you ran `npm run`. 70 71`npm run` sets the `NODE` environment variable to the `node` executable 72with which `npm` is executed. 73 74If you try to run a script without having a `node_modules` directory and it 75fails, you will be given a warning to run `npm install`, just in case you've 76forgotten. 77 78### Workspaces support 79 80You may use the [`workspace`](/using-npm/config#workspace) or 81[`workspaces`](/using-npm/config#workspaces) configs in order to run an 82arbitrary command from a package's `"scripts"` object in the context of the 83specified workspaces. If no `"command"` is provided, it will list the available 84scripts for each of these configured workspaces. 85 86Given a project with configured workspaces, e.g: 87 88``` 89. 90+-- package.json 91`-- packages 92 +-- a 93 | `-- package.json 94 +-- b 95 | `-- package.json 96 `-- c 97 `-- package.json 98``` 99 100Assuming the workspace configuration is properly set up at the root level 101`package.json` file. e.g: 102 103``` 104{ 105 "workspaces": [ "./packages/*" ] 106} 107``` 108 109And that each of the configured workspaces has a configured `test` script, 110we can run tests in all of them using the 111[`workspaces` config](/using-npm/config#workspaces): 112 113``` 114npm test --workspaces 115``` 116 117#### Filtering workspaces 118 119It's also possible to run a script in a single workspace using the `workspace` 120config along with a name or directory path: 121 122``` 123npm test --workspace=a 124``` 125 126The `workspace` config can also be specified multiple times in order to run a 127specific script in the context of multiple workspaces. When defining values for 128the `workspace` config in the command line, it also possible to use `-w` as a 129shorthand, e.g: 130 131``` 132npm test -w a -w b 133``` 134 135This last command will run `test` in both `./packages/a` and `./packages/b` 136packages. 137 138### Configuration 139 140#### `workspace` 141 142* Default: 143* Type: String (can be set multiple times) 144 145Enable running a command in the context of the configured workspaces of the 146current project while filtering by running only the workspaces defined by 147this configuration option. 148 149Valid values for the `workspace` config are either: 150 151* Workspace names 152* Path to a workspace directory 153* Path to a parent workspace directory (will result in selecting all 154 workspaces within that folder) 155 156When set for the `npm init` command, this may be set to the folder of a 157workspace which does not yet exist, to create the folder and set it up as a 158brand new workspace within the project. 159 160This value is not exported to the environment for child processes. 161 162#### `workspaces` 163 164* Default: null 165* Type: null or Boolean 166 167Set to true to run the command in the context of **all** configured 168workspaces. 169 170Explicitly setting this to false will cause commands like `install` to 171ignore workspaces altogether. When not set explicitly: 172 173- Commands that operate on the `node_modules` tree (install, update, etc.) 174will link workspaces into the `node_modules` folder. - Commands that do 175other things (test, exec, publish, etc.) will operate on the root project, 176_unless_ one or more workspaces are specified in the `workspace` config. 177 178This value is not exported to the environment for child processes. 179 180#### `include-workspace-root` 181 182* Default: false 183* Type: Boolean 184 185Include the workspace root when workspaces are enabled for a command. 186 187When false, specifying individual workspaces via the `workspace` config, or 188all workspaces via the `workspaces` flag, will cause npm to operate only on 189the specified workspaces, and not on the root project. 190 191This value is not exported to the environment for child processes. 192 193#### `if-present` 194 195* Default: false 196* Type: Boolean 197 198If true, npm will not exit with an error code when `run-script` is invoked 199for a script that isn't defined in the `scripts` section of `package.json`. 200This option can be used when it's desirable to optionally run a script when 201it's present and fail if the script fails. This is useful, for example, when 202running scripts that may only apply for some builds in an otherwise generic 203CI setup. 204 205This value is not exported to the environment for child processes. 206 207#### `ignore-scripts` 208 209* Default: false 210* Type: Boolean 211 212If true, npm does not run scripts specified in package.json files. 213 214Note that commands explicitly intended to run a particular script, such as 215`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` 216will still run their intended script if `ignore-scripts` is set, but they 217will *not* run any pre- or post-scripts. 218 219 220 221#### `foreground-scripts` 222 223* Default: false 224* Type: Boolean 225 226Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) 227scripts for installed packages in the foreground process, sharing standard 228input, output, and error with the main npm process. 229 230Note that this will generally make installs run slower, and be much noisier, 231but can be useful for debugging. 232 233 234 235#### `script-shell` 236 237* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows 238* Type: null or String 239 240The shell to use for scripts run with the `npm exec`, `npm run` and `npm 241init <package-spec>` commands. 242 243 244 245### See Also 246 247* [npm scripts](/using-npm/scripts) 248* [npm test](/commands/npm-test) 249* [npm start](/commands/npm-start) 250* [npm restart](/commands/npm-restart) 251* [npm stop](/commands/npm-stop) 252* [npm config](/commands/npm-config) 253* [npm workspaces](/using-npm/workspaces) 254