Permalink
Browse files

doc: Install scripts are an antipattern

  • Loading branch information...
1 parent 00f781f commit 7e6f0b8077b9c892391ed894a7bbe88f45fde152 @isaacs isaacs committed Dec 29, 2012
Showing with 49 additions and 4 deletions.
  1. +49 −4 doc/cli/scripts.md
View
@@ -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
@lacivert

lacivert Dec 30, 2012

tl;dr must be some typo?

@mfncooper

mfncooper Dec 30, 2012

Member

No, it means "too long; didn't read". See the Wikipedia entry.

+`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.

1 comment on commit 7e6f0b8

Contributor

creationix commented on 7e6f0b8 Jan 7, 2013

What about the use case of chaining to some other package manager? I've used the npm install hook to run component install or jam install.

And yes, for building binary addons, I completely agree that gyp should be used instead of an ad-hoc post install script.

Please sign in to comment.