doc: Install scripts are an antipattern

1 files changed, 49 insertions, 4 deletions

diff --git a/doc/cli/scripts.md b/doc/cli/scripts.md
index 3d33a8391..0eba5f7b1 100644
--- a/doc/cli/scripts.md
+++ b/doc/cli/scripts.md
@@ -6,6 +6,11 @@ npm-scripts(1) -- How npm handles the "scripts" field
 npm supports the "scripts" member of the package.json script, for the
 following scripts:
 
+* prepublish:
+  Run BEFORE the package is published.  (Also run on local `npm
+  install` without any arguments.)
+* publish, postpublish:
+  Run AFTER the package is published.
 * preinstall:
   Run BEFORE the package is installed
 * install, postinstall:
@@ -18,10 +23,6 @@ following scripts:
   Run BEFORE the package is updated with the update command.
 * update, postupdate:
   Run AFTER the package is updated with the update command.
-* prepublish:
-  Run BEFORE the package is published.
-* publish, postpublish:
-  Run AFTER the package is published.
 * pretest, test, posttest:
   Run by the `npm test` command.
 * prestop, stop, poststop:
@@ -35,6 +36,50 @@ following scripts:
 Additionally, arbitrary scrips can be run by doing
 `npm run-script <stage> <pkg>`.
 
+## NOTE: INSTALL SCRIPTS ARE AN ANTIPATTERN
+
+**tl;dr** Don't use `install`.  Use a `.gyp` file for compilation, and
+`prepublish` 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.  In early
+versions of node, this was often done using the `node-waf` scripts, or
+a standalone `Makefile`, and early versions of npm required that it be
+explicitly set in package.json.  This was not portable, and harder to
+do properly.
+
+In the current version of node, the standard way to do this is using a
+`.gyp` file.  If you have a file with a `.gyp` extension in the root
+of your package, then npm will run the appropriate `node-gyp` commands
+automatically at install time.  This is the only officially supported
+method for compiling binary addons, and does not require that you add
+anything to your package.json file.
+
+If you have to do other things before your package is used, in a way
+that is not dependent on the operating system or architecture of the
+target system, then use a `prepublish` script instead.  This includes
+tasks such as:
+
+* Compile CoffeeScript source code into JavaScript.
+* Create minified versions of JavaScript source code.
+* Fetching remote resources that your package will use.
+
+The advantage of doing these things at `prepublish` time instead of
+`preinstall` or `install` time is that they can be done once, in a
+single place, and thus greatly reduce complexity and variability.
+Additionally, this means that:
+
+* You can depend on `coffee-script` as a `devDependency`, and thus
+  your users don't need to have it installed.
+* You don't need to include the minifiers in your package, reducing
+  the size for your users.
+* You don't need to rely on your users having `curl` or `wget` or
+  other system tools on the target machines.
+
 ## DEFAULT VALUES
 
 npm will default some script values based on package contents.