diff options
Diffstat (limited to 'doc/misc/npm-scripts.md')
| -rw-r--r-- | doc/misc/npm-scripts.md | 32 |
1 files changed, 30 insertions, 2 deletions
diff --git a/doc/misc/npm-scripts.md b/doc/misc/npm-scripts.md index 241815fcd..05cb542ce 100644 --- a/doc/misc/npm-scripts.md +++ b/doc/misc/npm-scripts.md @@ -6,9 +6,14 @@ npm-scripts(7) -- How npm handles the "scripts" field npm supports the "scripts" property of the package.json script, for the following scripts: +* prepare: + Run both before the package is published, and on local `npm + install` without any arguments. (See below.) * prepublish: Run BEFORE the package is published. (Also run on local `npm - install` without any arguments.) + install` without any arguments. See below.) +* prepublishOnly: + Run BEFORE the package is published. (See below.) * publish, postpublish: Run AFTER the package is published. * preinstall: @@ -43,7 +48,30 @@ 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>`. -## COMMON USES +## PREPUBLISH AND PREPARE + +### DEPRECATION NOTE + +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). + +**IMPORTANT:** As of `npm@5`, `prepublish` will _only_ be run for `npm +publish`. This will make its behavior identical to `prepublishOnly`, so +`npm@6` or later may drop support for the use of `prepublishOnly`, and then +maybe we can all forget this embarrassing thing ever happened. + +See <https://github.com/npm/npm/issues/10074> for a much lengthier +justification, with further reading, for this change. + +### USE CASES 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 |