diff options
author | Zeke Sikelianos <zeke@sikelianos.com> | 2014-10-22 02:17:30 +0400 |
---|---|---|
committer | Forrest L Norvell <forrest@npmjs.com> | 2015-02-27 13:48:04 +0300 |
commit | 8ac6f2123a6af13dc9447fad96ec9cb583c45a71 (patch) | |
tree | 3bc191921c0f40f8425deda83fe3b52e800f39c5 /doc | |
parent | 7bf85cc372ab5698593b01e139c383fa62c92516 (diff) |
doc: soften warning against using install scripts
Keep some of the “don’t use install for compilation” verbiage, but
relegate it to bottom-of-the-page status.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/misc/npm-scripts.md | 45 |
1 files changed, 14 insertions, 31 deletions
diff --git a/doc/misc/npm-scripts.md b/doc/misc/npm-scripts.md index 3be4af377..e1380d1ed 100644 --- a/doc/misc/npm-scripts.md +++ b/doc/misc/npm-scripts.md @@ -34,46 +34,24 @@ run-script <pkg> <stage>`. *Pre* and *post* commands with matching names will be run for those as well (e.g. `premyscript`, `myscript`, `postmyscript`). -## 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 +## COMMON USES + +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 -target system, then use a `prepublish` script instead. This includes +target system, use a `prepublish` script. This includes tasks such as: -* Compile CoffeeScript source code into JavaScript. -* Create minified versions of JavaScript source code. +* Compiling CoffeeScript source code into JavaScript. +* Creating 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. +The advantage of doing these things at `prepublish` time is that they can be done once, in a +single place, thus reducing 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 +* You don't need to include 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. @@ -234,6 +212,11 @@ above. * Don't prefix your script commands with "sudo". If root permissions are required for some reason, then it'll fail with that error, and the user will sudo the npm command in question. +* 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. ## SEE ALSO |