kartykp/upgrade-path-to-regex
@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
| 1 | --- |
| 2 | title: scripts |
| 3 | section: 7 |
| 4 | description: How npm handles the "scripts" field |
| 5 | github_repo: npm/cli |
| 6 | github_branch: latest |
| 7 | github_path: docs/lib/content/using-npm/scripts.md |
| 8 | redirect_from: |
| 9 | - /cli-documentation/misc/scripts |
| 10 | - /cli-documentation/using-npm/scripts |
| 11 | - /cli-documentation/v10/misc/scripts |
| 12 | - /cli-documentation/v10/using-npm/scripts |
| 13 | - /cli/misc/scripts |
| 14 | - /cli/using-npm/scripts |
| 15 | - /cli/v10/misc/scripts |
| 16 | - /misc/scripts |
| 17 | - /using-npm/scripts |
| 18 | --- |
| 19 | |
| 20 | ### Description |
| 21 | |
| 22 | The `"scripts"` property of your `package.json` file supports a number of built-in scripts and their preset life cycle events as well as arbitrary scripts. These all can be executed by running `npm run-script <stage>` or `npm run <stage>` for short. _Pre_ and _post_ commands with matching names will be run for those as well (e.g. `premyscript`, `myscript`, `postmyscript`). Scripts from dependencies can be run with `npm explore <pkg> -- npm run <stage>`. |
| 23 | |
| 24 | ### Pre & Post Scripts |
| 25 | |
| 26 | To create "pre" or "post" scripts for any scripts defined in the `"scripts"` section of the `package.json`, simply create another script _with a matching name_ and add "pre" or "post" to the beginning of them. |
| 27 | |
| 28 | ```json |
| 29 | { |
| 30 | "scripts": { |
| 31 | "precompress": "{{ executes BEFORE the `compress` script }}", |
| 32 | "compress": "{{ run command to compress files }}", |
| 33 | "postcompress": "{{ executes AFTER `compress` script }}" |
| 34 | } |
| 35 | } |
| 36 | ``` |
| 37 | |
| 38 | In this example `npm run compress` would execute these scripts as described. |
| 39 | |
| 40 | ### Life Cycle Scripts |
| 41 | |
| 42 | There are some special life cycle scripts that happen only in certain situations. These scripts happen in addition to the `pre<event>`, `post<event>`, and `<event>` scripts. |
| 43 | |
| 44 | - `prepare`, `prepublish`, `prepublishOnly`, `prepack`, `postpack`, `dependencies` |
| 45 | |
| 46 | **prepare** (since `npm@4.0.0`) |
| 47 | |
| 48 | - Runs BEFORE the package is packed, i.e. during `npm publish` and `npm pack` |
| 49 | - Runs on local `npm install` without any arguments |
| 50 | - Runs AFTER `prepublish`, but BEFORE `prepublishOnly` |
| 51 | |
| 52 | - NOTE: If a package being installed through git contains a `prepare` script, its `dependencies` and `devDependencies` will be installed, and the prepare script will be run, before the package is packaged and installed. |
| 53 | |
| 54 | - As of `npm@7` these scripts run in the background. To see the output, run with: `--foreground-scripts`. |
| 55 | |
| 56 | **prepublish** (DEPRECATED) |
| 57 | |
| 58 | - Does not run during `npm publish`, but does run during `npm ci` and `npm install`. See below for more info. |
| 59 | |
| 60 | **prepublishOnly** |
| 61 | |
| 62 | - Runs BEFORE the package is prepared and packed, ONLY on `npm publish`. |
| 63 | |
| 64 | **prepack** |
| 65 | |
| 66 | - Runs BEFORE a tarball is packed (on "`npm pack`", "`npm publish`", and when installing a git dependency). |
| 67 | - NOTE: "`npm run pack`" is NOT the same as "`npm pack`". "`npm run pack`" is an arbitrary user defined script name, where as, "`npm pack`" is a CLI defined command. |
| 68 | |
| 69 | **postpack** |
| 70 | |
| 71 | - Runs AFTER the tarball has been generated but before it is moved to its final destination (if at all, publish does not save the tarball locally) |
| 72 | |
| 73 | **dependencies** |
| 74 | |
| 75 | - Runs AFTER any operations that modify the `node_modules` directory IF changes occurred. |
| 76 | - Does NOT run in global mode |
| 77 | |
| 78 | #### Prepare and Prepublish |
| 79 | |
| 80 | **Deprecation Note: prepublish** |
| 81 | |
| 82 | Since `npm@1.1.71`, the npm CLI has run the `prepublish` script for both `npm publish` and `npm install`, because it's a convenient way to prepare a package for use (some common use cases are described in the section below). It has also turned out to be, in practice, [very confusing](https://github.com/npm/npm/issues/10074). As of `npm@4.0.0`, a new event has been introduced, `prepare`, that preserves this existing behavior. A _new_ event, `prepublishOnly` has been added as a transitional strategy to allow users to avoid the confusing behavior of existing npm versions and only run on `npm publish` (for instance, running the tests one last time to ensure they're in good shape). |
| 83 | |
| 84 | See [https://github.com/npm/npm/issues/10074](https://github.com/npm/npm/issues/10074) for a much lengthier justification, with further reading, for this change. |
| 85 | |
| 86 | **Use Cases** |
| 87 | |
| 88 | If you need to perform operations on your package before it is used, in a way that is not dependent on the operating system or architecture of the target system, use a `prepublish` script. This includes tasks such as: |
| 89 | |
| 90 | - Compiling CoffeeScript source code into JavaScript. |
| 91 | - Creating minified versions of JavaScript source code. |
| 92 | - Fetching remote resources that your package will use. |
| 93 | |
| 94 | The advantage of doing these things at `prepublish` time is that they can be done once, in a single place, thus reducing complexity and variability. Additionally, this means that: |
| 95 | |
| 96 | - You can depend on `coffee-script` as a `devDependency`, and thus your users don't need to have it installed. |
| 97 | - You don't need to include minifiers in your package, reducing the size for your users. |
| 98 | - You don't need to rely on your users having `curl` or `wget` or other system tools on the target machines. |
| 99 | |
| 100 | #### Dependencies |
| 101 | |
| 102 | The `dependencies` script is run any time an `npm` command causes changes to the `node_modules` directory. It is run AFTER the changes have been applied and the `package.json` and `package-lock.json` files have been updated. |
| 103 | |
| 104 | ### Life Cycle Operation Order |
| 105 | |
| 106 | #### [`npm cache add`](/cli/v10/commands/npm-cache) |
| 107 | |
| 108 | - `prepare` |
| 109 | |
| 110 | #### [`npm ci`](/cli/v10/commands/npm-ci) |
| 111 | |
| 112 | - `preinstall` |
| 113 | - `install` |
| 114 | - `postinstall` |
| 115 | - `prepublish` |
| 116 | - `preprepare` |
| 117 | - `prepare` |
| 118 | - `postprepare` |
| 119 | |
| 120 | These all run after the actual installation of modules into `node_modules`, in order, with no internal actions happening in between |
| 121 | |
| 122 | #### [`npm diff`](/cli/v10/commands/npm-diff) |
| 123 | |
| 124 | - `prepare` |
| 125 | |
| 126 | #### [`npm install`](/cli/v10/commands/npm-install) |
| 127 | |
| 128 | These also run when you run `npm install -g <pkg-name>` |
| 129 | |
| 130 | - `preinstall` |
| 131 | - `install` |
| 132 | - `postinstall` |
| 133 | - `prepublish` |
| 134 | - `preprepare` |
| 135 | - `prepare` |
| 136 | - `postprepare` |
| 137 | |
| 138 | If there is a `binding.gyp` file in the root of your package and you haven't defined your own `install` or `preinstall` scripts, npm will default the `install` command to compile using node-gyp via `node-gyp rebuild` |
| 139 | |
| 140 | These are run from the scripts of `<pkg-name>` |
| 141 | |
| 142 | #### [`npm pack`](/cli/v10/commands/npm-pack) |
| 143 | |
| 144 | - `prepack` |
| 145 | - `prepare` |
| 146 | - `postpack` |
| 147 | |
| 148 | #### [`npm publish`](/cli/v10/commands/npm-publish) |
| 149 | |
| 150 | - `prepublishOnly` |
| 151 | - `prepack` |
| 152 | - `prepare` |
| 153 | - `postpack` |
| 154 | - `publish` |
| 155 | - `postpublish` |
| 156 | |
| 157 | #### [`npm rebuild`](/cli/v10/commands/npm-rebuild) |
| 158 | |
| 159 | - `preinstall` |
| 160 | - `install` |
| 161 | - `postinstall` |
| 162 | - `prepare` |
| 163 | |
| 164 | `prepare` is only run if the current directory is a symlink (e.g. with linked packages) |
| 165 | |
| 166 | #### [`npm restart`](/cli/v10/commands/npm-restart) |
| 167 | |
| 168 | If there is a `restart` script defined, these events are run, otherwise `stop` and `start` are both run if present, including their `pre` and `post` iterations) |
| 169 | |
| 170 | - `prerestart` |
| 171 | - `restart` |
| 172 | - `postrestart` |
| 173 | |
| 174 | #### [`npm run <user defined>`](/cli/v10/commands/npm-run-script) |
| 175 | |
| 176 | - `pre<user-defined>` |
| 177 | - `<user-defined>` |
| 178 | - `post<user-defined>` |
| 179 | |
| 180 | #### [`npm start`](/cli/v10/commands/npm-start) |
| 181 | |
| 182 | - `prestart` |
| 183 | - `start` |
| 184 | - `poststart` |
| 185 | |
| 186 | If there is a `server.js` file in the root of your package, then npm will default the `start` command to `node server.js`. `prestart` and `poststart` will still run in this case. |
| 187 | |
| 188 | #### [`npm stop`](/cli/v10/commands/npm-stop) |
| 189 | |
| 190 | - `prestop` |
| 191 | - `stop` |
| 192 | - `poststop` |
| 193 | |
| 194 | #### [`npm test`](/cli/v10/commands/npm-test) |
| 195 | |
| 196 | - `pretest` |
| 197 | - `test` |
| 198 | - `posttest` |
| 199 | |
| 200 | #### [`npm version`](/cli/v10/commands/npm-version) |
| 201 | |
| 202 | - `preversion` |
| 203 | - `version` |
| 204 | - `postversion` |
| 205 | |
| 206 | #### A Note on a lack of [`npm uninstall`](/cli/v10/commands/npm-uninstall) scripts |
| 207 | |
| 208 | While npm v6 had `uninstall` lifecycle scripts, npm v7 does not. Removal of a package can happen for a wide variety of reasons, and there's no clear way to currently give the script enough context to be useful. |
| 209 | |
| 210 | Reasons for a package removal include: |
| 211 | |
| 212 | - a user directly uninstalled this package |
| 213 | - a user uninstalled a dependant package and so this dependency is being uninstalled |
| 214 | - a user uninstalled a dependant package but another package also depends on this version |
| 215 | - this version has been merged as a duplicate with another version |
| 216 | - etc. |
| 217 | |
| 218 | Due to the lack of necessary context, `uninstall` lifecycle scripts are not implemented and will not function. |
| 219 | |
| 220 | ### User |
| 221 | |
| 222 | When npm is run as root, scripts are always run with the effective uid and gid of the working directory owner. |
| 223 | |
| 224 | ### Environment |
| 225 | |
| 226 | Package scripts run in an environment where many pieces of information are made available regarding the setup of npm and the current state of the process. |
| 227 | |
| 228 | #### path |
| 229 | |
| 230 | If you depend on modules that define executable scripts, like test suites, then those executables will be added to the `PATH` for executing the scripts. So, if your package.json has this: |
| 231 | |
| 232 | ```json |
| 233 | { |
| 234 | "name": "foo", |
| 235 | "dependencies": { |
| 236 | "bar": "0.1.x" |
| 237 | }, |
| 238 | "scripts": { |
| 239 | "start": "bar ./test" |
| 240 | } |
| 241 | } |
| 242 | ``` |
| 243 | |
| 244 | then you could run `npm start` to execute the `bar` script, which is exported into the `node_modules/.bin` directory on `npm install`. |
| 245 | |
| 246 | #### package.json vars |
| 247 | |
| 248 | The package.json fields are tacked onto the `npm_package_` prefix. So, for instance, if you had `{"name":"foo", "version":"1.2.5"}` in your package.json file, then your package scripts would have the `npm_package_name` environment variable set to "foo", and the `npm_package_version` set to "1.2.5". You can access these variables in your code with `process.env.npm_package_name` and `process.env.npm_package_version`, and so on for other fields. |
| 249 | |
| 250 | See [`package.json`](/cli/v10/configuring-npm/package-json) for more on package configs. |
| 251 | |
| 252 | #### current lifecycle event |
| 253 | |
| 254 | Lastly, the `npm_lifecycle_event` environment variable is set to whichever stage of the cycle is being executed. So, you could have a single script used for different parts of the process which switches based on what's currently happening. |
| 255 | |
| 256 | Objects are flattened following this format, so if you had `{"scripts":{"install":"foo.js"}}` in your package.json, then you'd see this in the script: |
| 257 | |
| 258 | ```bash |
| 259 | process.env.npm_package_scripts_install === "foo.js" |
| 260 | ``` |
| 261 | |
| 262 | ### Examples |
| 263 | |
| 264 | For example, if your package.json contains this: |
| 265 | |
| 266 | ```json |
| 267 | { |
| 268 | "scripts": { |
| 269 | "install": "scripts/install.js", |
| 270 | "postinstall": "scripts/install.js" |
| 271 | } |
| 272 | } |
| 273 | ``` |
| 274 | |
| 275 | then `scripts/install.js` will be called for the install and post-install stages of the lifecycle. Since `scripts/install.js` is running for two different phases, it would be wise in this case to look at the `npm_lifecycle_event` environment variable. |
| 276 | |
| 277 | If you want to run a make command, you can do so. This works just fine: |
| 278 | |
| 279 | ```json |
| 280 | { |
| 281 | "scripts": { |
| 282 | "preinstall": "./configure", |
| 283 | "install": "make && make install", |
| 284 | "test": "make test" |
| 285 | } |
| 286 | } |
| 287 | ``` |
| 288 | |
| 289 | ### Exiting |
| 290 | |
| 291 | Scripts are run by passing the line as a script argument to `sh`. |
| 292 | |
| 293 | If the script exits with a code other than 0, then this will abort the process. |
| 294 | |
| 295 | Note that these script files don't have to be Node.js or even JavaScript programs. They just have to be some kind of executable file. |
| 296 | |
| 297 | ### Best Practices |
| 298 | |
| 299 | - Don't exit with a non-zero error code unless you _really_ mean it. If the failure is minor or only will prevent some optional features, then it's better to just print a warning and exit successfully. |
| 300 | - Try not to use scripts to do what npm can do for you. Read through [`package.json`](/cli/v10/configuring-npm/package-json) to see all the things that you can specify and enable by simply describing your package appropriately. In general, this will lead to a more robust and consistent state. |
| 301 | - Inspect the env to determine where to put things. For instance, if the `npm_config_binroot` environment variable is set to `/home/user/bin`, then don't try to install executables into `/usr/local/bin`. The user probably set it up that way for a reason. |
| 302 | - Don't prefix your script commands with "sudo". If root permissions are required for some reason, then it'll fail with that error, and the user will sudo the npm command in question. |
| 303 | - Don't use `install`. Use a `.gyp` file for compilation, and `prepare` for anything else. You should almost never have to explicitly set a preinstall or install script. If you are doing this, please consider if there is another option. The only valid use of `install` or `preinstall` scripts is for compilation which must be done on the target architecture. |
| 304 | - Scripts are run from the root of the package folder, regardless of what the current working directory is when `npm` is invoked. 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`. |
| 305 | |
| 306 | ### See Also |
| 307 | |
| 308 | - [npm run-script](/cli/v10/commands/npm-run-script) |
| 309 | - [package.json](/cli/v10/configuring-npm/package-json) |
| 310 | - [npm developers](/cli/v10/using-npm/developers) |
| 311 | - [npm install](/cli/v10/commands/npm-install) |