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