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 to selecting all of
139 the nested workspaces)
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: false
153 • Type: Boolean
155 Enable running a command in the context of all the configured
158 workspaces.
159 This value is not exported to the environment for child processes.
161 <!-- automatically generated, do not edit manually --> <!-- see
162 lib/utils/config/definitions.js -->
163 if-present
166 • Default: false
167 • Type: Boolean
169 If true, npm will not exit with an error code when run-script is in‐
172 voked for a script that isn't defined in the scripts section of pack‐
173 age.json. This option can be used when it's desirable to optionally
174 run a script when it's present and fail if the script fails. This is
175 useful, for example, when running scripts that may only apply for some
176 builds in an otherwise generic CI setup. <!-- automatically generated,
177 do not edit manually --> <!-- see lib/utils/config/definitions.js -->
178 ignore-scripts
181 • Default: false
182 • Type: Boolean
184 If true, npm does not run scripts specified in package.json files.
187 Note that commands explicitly intended to run a particular script, such
189 as npm start, npm stop, npm restart, npm test, and npm run-script will
190 still run their intended script if ignore-scripts is set, but they will
191 not run any pre- or post-scripts. <!-- automatically generated, do not
192 edit manually --> <!-- see lib/utils/config/definitions.js -->
193 script-shell
196 • Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows
197 • Type: null or String
199 The shell to use for scripts run with the npm exec, npm run and npm
202 init <pkg> commands. <!-- automatically generated, do not edit manu‐
203 ally --> <!-- see lib/utils/config/definitions.js -->
204 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
206 See Also
209 • npm help scripts
210 • npm help test
212 • npm help start
214 • npm help restart
216 • npm help stop
218 • npm help config
220 • npm help workspaces
222 October 2021 NPM-RUN-SCRIPT(1)