diff options
author | Forrest L Norvell <forrest@npmjs.com> | 2016-10-15 05:20:04 +0300 |
---|---|---|
committer | Kat Marchán <kzm@sykosomatic.org> | 2016-10-20 03:24:59 +0300 |
commit | c12bbf8c5a5dff24a191b66ac638f552bfb76601 (patch) | |
tree | c885deb17b015d25edffbb6e3b168fc0eea69695 /doc | |
parent | 52fdefddb48f0c39c6e8eb4c118eb306c9436117 (diff) |
doc: document prepublish-on-install deprecation
Now all we have to remember to do is come back to this when we put out
`npm@5`.
PR-URL: https://github.com/npm/npm/pull/14290
Credit: @othiym23
Reviewed-By: @watilde
Reviewed-By: @iarna
Reviewed-By: @zkat
Diffstat (limited to 'doc')
-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 |