1NPM-RUN-SCRIPT(1)                                            NPM-RUN-SCRIPT(1)
2
3
4

NAME

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