@cryptotaxi247 / documentation
Code Commits Issues Pulls Sessions CI/CD
reggi/overrides
@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 217 lines 8.55 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: latest
7 github_path: docs/lib/content/commands/npm-run-script.md
8 redirect_from:
9 - /cli-commands/npm-run-script
10 - /cli-commands/run-script
11 - /cli-documentation/cli-commands/npm-run-script
12 - /cli-documentation/cli-commands/run-script
13 - /cli-documentation/commands/npm-run-script
14 - /cli-documentation/commands/run-script
15 - /cli-documentation/npm-run-script
16 - /cli-documentation/run-script
17 - /cli-documentation/v10/cli-commands/npm-run-script
18 - /cli-documentation/v10/cli-commands/run-script
19 - /cli-documentation/v10/commands/npm-run-script
20 - /cli-documentation/v10/commands/run-script
21 - /cli-documentation/v10/npm-run-script
22 - /cli-documentation/v10/run-script
23 - /cli/cli-commands/npm-run-script
24 - /cli/cli-commands/run-script
25 - /cli/commands/npm-run-script
26 - /cli/commands/run-script
27 - /cli/npm-run-script
28 - /cli/run-script
29 - /cli/v10/cli-commands/npm-run-script
30 - /cli/v10/cli-commands/run-script
31 - /cli/v10/commands/run-script
32 - /cli/v10/npm-run-script
33 - /cli/v10/run-script
34 - /commands/npm-run-script
35 - /commands/run-script
36 ---
37
38 ### Synopsis
39
40 ```bash
41 npm run-script <command> [-- <args>]
42
43 aliases: run, rum, urn
44 ```
45
46 ### Description
47
48 This runs an arbitrary command from a package's `"scripts"` object. If no `"command"` is provided, it will list the available scripts.
49
50 `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.
51
52 Any positional arguments are passed to the specified script. Use `--` to pass `-`-prefixed flags and options which would otherwise be parsed by npm.
53
54 For example:
55
56 ```bash
57 npm run test -- --grep="pattern"
58 ```
59
60 The arguments will only be passed to the script specified after `npm run` and not to any `pre` or `post` script.
61
62 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.
63
64 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:
65
66 ```bash
67 "scripts": {"test": "tap test/*.js"}
68 ```
69
70 instead of
71
72 ```bash
73 "scripts": {"test": "node_modules/.bin/tap test/*.js"}
74 ```
75
76 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` config](/cli/v10/using-npm/config#script-shell).
77
78 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`.
79
80 `npm run` sets the `NODE` environment variable to the `node` executable with which `npm` is executed.
81
82 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.
83
84 ### Workspaces support
85
86 You may use the [`workspace`](/cli/v10/using-npm/config#workspace) or [`workspaces`](/cli/v10/using-npm/config#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.
87
88 Given a project with configured workspaces, e.g:
89
90 ```
91 .
92 +-- package.json
93 `-- packages
94 +-- a
95 | `-- package.json
96 +-- b
97 | `-- package.json
98 `-- c
99 `-- package.json
100 ```
101
102 Assuming the workspace configuration is properly set up at the root level `package.json` file. e.g:
103
104 ```
105 {
106 "workspaces": [ "./packages/*" ]
107 }
108 ```
109
110 And that each of the configured workspaces has a configured `test` script, we can run tests in all of them using the [`workspaces` config](/cli/v10/using-npm/config#workspaces):
111
112 ```
113 npm test --workspaces
114 ```
115
116 #### Filtering workspaces
117
118 It's also possible to run a script in a single workspace using the `workspace` config along with a name or directory path:
119
120 ```
121 npm test --workspace=a
122 ```
123
124 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:
125
126 ```
127 npm test -w a -w b
128 ```
129
130 This last command will run `test` in both `./packages/a` and `./packages/b` packages.
131
132 ### Configuration
133
134 #### `workspace`
135
136 - Default:
137 - Type: String (can be set multiple times)
138
139 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.
140
141 Valid values for the `workspace` config are either:
142
143 - Workspace names
144 - Path to a workspace directory
145 - Path to a parent workspace directory (will result in selecting all workspaces within that folder)
146
147 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.
148
149 This value is not exported to the environment for child processes.
150
151 #### `workspaces`
152
153 - Default: null
154 - Type: null or Boolean
155
156 Set to true to run the command in the context of **all** configured workspaces.
157
158 Explicitly setting this to false will cause commands like `install` to ignore workspaces altogether. When not set explicitly:
159
160 - 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.
161
162 This value is not exported to the environment for child processes.
163
164 #### `include-workspace-root`
165
166 - Default: false
167 - Type: Boolean
168
169 Include the workspace root when workspaces are enabled for a command.
170
171 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.
172
173 This value is not exported to the environment for child processes.
174
175 #### `if-present`
176
177 - Default: false
178 - Type: Boolean
179
180 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.
181
182 This value is not exported to the environment for child processes.
183
184 #### `ignore-scripts`
185
186 - Default: false
187 - Type: Boolean
188
189 If true, npm does not run scripts specified in package.json files.
190
191 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.
192
193 #### `foreground-scripts`
194
195 - Default: `false` unless when using `npm pack` or `npm publish` where it defaults to `true`
196 - Type: Boolean
197
198 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.
199
200 Note that this will generally make installs run slower, and be much noisier, but can be useful for debugging.
201
202 #### `script-shell`
203
204 - Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows
205 - Type: null or String
206
207 The shell to use for scripts run with the `npm exec`, `npm run` and `npm init <package-spec>` commands.
208
209 ### See Also
210
211 - [npm scripts](/cli/v10/using-npm/scripts)
212 - [npm test](/cli/v10/commands/npm-test)
213 - [npm start](/cli/v10/commands/npm-start)
214 - [npm restart](/cli/v10/commands/npm-restart)
215 - [npm stop](/cli/v10/commands/npm-stop)
216 - [npm config](/cli/v10/commands/npm-config)
217 - [npm workspaces](/cli/v10/using-npm/workspaces)