From c12bbf8c5a5dff24a191b66ac638f552bfb76601 Mon Sep 17 00:00:00 2001 From: Forrest L Norvell Date: Fri, 14 Oct 2016 19:20:04 -0700 Subject: 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 --- doc/misc/npm-scripts.md | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) (limited to 'doc') 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 -- npm run `. -## 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 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 -- cgit v1.2.3