@@ -6,6 +6,11 @@ npm-scripts(1) -- How npm handles the "scripts" field
66npm supports the "scripts" member of the package.json script, for the
77following scripts:
88
9+ * prepublish:
10+ Run BEFORE the package is published. (Also run on local `npm
11+ install` without any arguments.)
12+ * publish, postpublish:
13+ Run AFTER the package is published.
914* preinstall:
1015 Run BEFORE the package is installed
1116* install, postinstall:
@@ -18,10 +23,6 @@ following scripts:
1823 Run BEFORE the package is updated with the update command.
1924* update, postupdate:
2025 Run AFTER the package is updated with the update command.
21- * prepublish:
22- Run BEFORE the package is published.
23- * publish, postpublish:
24- Run AFTER the package is published.
2526* pretest, test, posttest:
2627 Run by the ` npm test ` command.
2728* prestop, stop, poststop:
@@ -35,6 +36,50 @@ following scripts:
3536Additionally, arbitrary scrips can be run by doing
3637` npm run-script <stage> <pkg> ` .
3738
39+ ## NOTE: INSTALL SCRIPTS ARE AN ANTIPATTERN
40+
41+ ** tl;dr** Don't use ` install ` . Use a ` .gyp ` file for compilation, and
42+ ` prepublish ` for anything else.
43+
44+ You should almost never have to explicitly set a ` preinstall ` or
45+ ` install ` script. If you are doing this, please consider if there is
46+ another option.
47+
48+ The only valid use of ` install ` or ` preinstall ` scripts is for
49+ compilation which must be done on the target architecture. In early
50+ versions of node, this was often done using the ` node-waf ` scripts, or
51+ a standalone ` Makefile ` , and early versions of npm required that it be
52+ explicitly set in package.json. This was not portable, and harder to
53+ do properly.
54+
55+ In the current version of node, the standard way to do this is using a
56+ ` .gyp ` file. If you have a file with a ` .gyp ` extension in the root
57+ of your package, then npm will run the appropriate ` node-gyp ` commands
58+ automatically at install time. This is the only officially supported
59+ method for compiling binary addons, and does not require that you add
60+ anything to your package.json file.
61+
62+ If you have to do other things before your package is used, in a way
63+ that is not dependent on the operating system or architecture of the
64+ target system, then use a ` prepublish ` script instead. This includes
65+ tasks such as:
66+
67+ * Compile CoffeeScript source code into JavaScript.
68+ * Create minified versions of JavaScript source code.
69+ * Fetching remote resources that your package will use.
70+
71+ The advantage of doing these things at ` prepublish ` time instead of
72+ ` preinstall ` or ` install ` time is that they can be done once, in a
73+ single place, and thus greatly reduce complexity and variability.
74+ Additionally, this means that:
75+
76+ * You can depend on ` coffee-script ` as a ` devDependency ` , and thus
77+ your users don't need to have it installed.
78+ * You don't need to include the minifiers in your package, reducing
79+ the size for your users.
80+ * You don't need to rely on your users having ` curl ` or ` wget ` or
81+ other system tools on the target machines.
82+
3883## DEFAULT VALUES
3984
4085npm will default some script values based on package contents.
0 commit comments