1NPM-RUN-SCRIPT(1) NPM-RUN-SCRIPT(1)
2
6 npm-run-script - Run arbitrary package scripts
7 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 aliases: run, rum, urn
14 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 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 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 For example:
29 npm run test -- --grep="pattern"
31 The arguments will only be passed to the script specified after npm run
33 and not to any pre or post script.
34 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 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 "scripts": {"test": "tap test/*.js"}
47 instead of
49 "scripts": {"test": "node_modules/.bin/tap test/*.js"}
51 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 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 npm run sets the NODE environment variable to the node executable with
65 which npm is executed.
66 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 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 Given a project with configured workspaces, e.g:
78 .
80 +-- package.json
81 `-- packages
82 +-- a
83 | `-- package.json
84 +-- b
85 | `-- package.json
86 `-- c
87 `-- package.json
88 Assuming the workspace configuration is properly set up at the root
90 level package.json file. e.g:
91 {
93 "workspaces": [ "./packages/*" ]
94 }
95 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 npm test --workspaces
100 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 npm test --workspace=a
106 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 npm test -w a -w b
113 This last command will run test in both ./packages/a and ./packages/b
115 packages.
116 Configuration
118 <!-- AUTOGENERATED CONFIG DESCRIPTIONS START --> <!-- automatically
119 generated, do not edit manually --> <!-- see lib/utils/config/defini‐
120 tions.js -->
121 workspace
123 • Default:
124 • Type: String (can be set multiple times)
126 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 Valid values for the workspace config are either:
133 • Workspace names
135 • Path to a workspace directory
137 • Path to a parent workspace directory (will result in selecting all
139 workspaces within that folder)
140 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 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 workspaces
152 • Default: null
153 • Type: null or Boolean
155 Set to true to run the command in the context of all configured
158 workspaces.
159 Explicitly setting this to false will cause commands like install to
161 ignore workspaces altogether. When not set explicitly:
162 • 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 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 include-workspace-root
176 • Default: false
177 • Type: Boolean
179 Include the workspace root when workspaces are enabled for a command.
182 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 if-present
191 • Default: false
192 • Type: Boolean
194 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 ignore-scripts
206 • Default: false
207 • Type: Boolean
209 If true, npm does not run scripts specified in package.json files.
212 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 script-shell
221 • Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows
222 • Type: null or String
224 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 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
231 See Also
234 • npm help scripts
235 • npm help test
237 • npm help start
239 • npm help restart
241 • npm help stop
243 • npm help config
245 • npm help workspaces
247 January 2022 NPM-RUN-SCRIPT(1)